Topology Schema¶

The topology is defined in a single YAML file. The schema is validated by Pydantic; extra keys are forbidden everywhere.

Top-level structure¶

global:    # GlobalConfig
defaults:  # DefaultsConfig
groups:    # list[Group]
users:     # list[User]
portals:   # list[Portal]  (optional)
routing:   # RoutingConfig
regions:   # list[Region]

global¶

global.cdn¶

defaults¶

Default configuration applied to all exit or hub nodes. Node-level fields override these.

defaults.exit¶

defaults.hub¶

KeysConfig¶

ExitConnectionsConfig¶

ObservatoryConfig¶

XdnsConfig¶

Configures a DNS-interception inbound on hub nodes — VLESS over mKCP that intercepts queries for the listed domains. Only users whose access includes xdns are added as clients.

WireguardConfig¶

Configures a WireGuard inbound on hub nodes. Peer keypairs are derived deterministically from each identity and the hub's Reality private key (see Architecture). Only users whose access includes wireguard become peers; their server identity and guests are allocated too.

HysteriaConfig¶

Configures a Hysteria 2 listener (QUIC over UDP). On hub nodes it admits users whose access includes hysteria (plus their server identity and guests); on exit nodes it admits the hub-exit identities of every hub, and hubs dial it when the exit region sets protocol: hysteria. Every field has a default, so hysteria: {} is a complete config.

Hysteria requires a real TLS certificate (Xray rejects Reality here). By default HexRift derives a self-signed leaf for the SNI from the node's Reality private key (key_type selects ed25519 or ecdsa-p256) and embeds it inline; peers pin its SHA-256 (pinnedPeerCertSha256 on hub outbounds, pinSHA256 in share URLs). Set certificate to serve an operator-issued cert instead — then sni is required; without pin_sha256 hub outbounds verify against CA roots and share URLs carry insecure=0, with it peers pin that fingerprint exactly as they pin the derived cert.

Auth is the identity UUID, so a client that rewrites the UUID's third segment selects an exit region exactly like a VLESS client does (vlessRoute), and warp variants work unchanged.

Official Hysteria, sing-box and mihomo accept either key type. Xray's Hysteria dialer parrots Chrome's QUIC ClientHello by default and can only negotiate ecdsa-p256: HexRift disables the parrot on hub→exit dials to ed25519 exits, but a hysteria2:// share URL carries no such switch, so a hub listener that Xray-based client apps dial should set key_type: ecdsa-p256. Share URLs carry insecure=1&pinSHA256=… — a client that honours the pin verifies the exact cert, a client that ignores it connects unverified; switch to certificate if that matters.

TlsConfig¶

Serves the hub's direct inbound as VLESS over XHTTP secured by plain TLS with an operator-issued certificate, in place of Reality. Meant for clients behind TLS-intercepting proxies, which re-terminate the handshake and so break Reality but pass ordinary HTTPS to a publicly trusted certificate. The SNI and the XHTTP Host are the node hostname, so the certificate at those paths must cover each node in the region; ALPN is h2,http/1.1. Xray re-reads the certificate files every hour, so an ACME renewal needs no restart. Everything else about the inbound is unchanged.

A hub region serves exactly one of Reality or TLS: defaults.hub sets one of reality / tls, and a region's own reality: or tls: block replaces that choice for all its nodes. Hysteria is not available on TLS regions.

CertificateFiles¶

HysteriaCertificate is the same pair plus an optional pin_sha256.

groups¶

List of user groups. Groups provide a shared shortId for Reality inbound filtering.

If short_id is omitted it is derived as SHA256("{id}.{namespace}")[:16].

Example:

groups:
  - id: staff
  - id: vip
    short_id: deadbeef01234567

users¶

Access types¶

Example:

users:
  - username: alice
    group: staff
    access: [xhttp, cdn]
    guests: [alice-phone, alice-tablet]

portals¶

Site-to-site reverse tunnels. A portal is a machine (e.g. a home server) that dials every hub with a dedicated identity and opens a reverse tunnel; hub traffic from the portal's member users that matches routes is sent backward through that tunnel and egresses on the portal machine. Several machines may run the same portal config — Xray pools their tunnels and load-balances across them.

PortalRoutes¶

At least one matcher is required.

Matchers are evaluated on the hub, before the connection leaves it, so the hub has to recognize the destination on its own. A bare LAN hostname (nas, router) never gets there — the hub cannot resolve it, the rule falls through, and the traffic goes to routing.hub_default. Use a matcher that catches the name as written (domain:lan, full:nas.home.arpa), or publish a port instead. ips likewise matches only what the client dialed as an IP literal — the hub never resolves a name to test it against a CIDR (see strict).

Portal ids must not collide with node or region ids, and the derived {id}-portal tag must not start with an exit region id (balancer selectors are prefix matches). The portal UUID is derived as UUID5(namespace_uuid, "portal/{id}") and is reverse-only: Xray rejects forward proxying with it. If no portal machine is connected, matching traffic is dropped (no fallback to the default route).

A portal dials with its own shortId, SHA256("{id}.portal.{namespace}")[:16], which every hub node accepts alongside the group and per-user ones. Its identity is therefore independent of the groups its members belong to, and rotating one portal's shortId leaves every other portal and user untouched.

Members are selected by user_email in the hub routing rule, so each one needs an access type that carries it — xhttp, tls, cdn, xdns, wireguard, or hysteria — and that access type has to render on a hub node (for hysteria, a hub with a Hysteria inbound). Declaring cdn without a global.cdn block, or wireguard/xdns without the matching config, emits no inbound carrying the member's identity, so the rule would match no traffic; both cases are rejected at validation time.

A proxy-only or server-only member is rejected as well.

Only a member's own identity routes into the portal. Guests ({label}@{username}) and server identities ({username}-server@{username}) are separate emails that the rule never matches, so a guest cannot reach a portal even when its user is a member. Listing a guest label in portals[].users is not a way around this - this is made for security by design.

PortalPublish¶

publish forwards a port into the tunnel — the ingress direction, the mirror of routes. Each selected hub node binds the port and hands every accepted connection to the portal machine, which dials target locally.

Each entry adds a dokodemo-door inbound tagged {id}-publish-{port} to the selected hub nodes, plus routing rules placed ahead of every other hub rule — before the DNS rule — so no later domain or IP rule can re-steer a published connection. With allow, sources outside the list are blocked; without it, every source is accepted. Sniffing is disabled on these inbounds: the target is fixed, so a client-supplied SNI has nothing to contribute and must not influence routing.

target is resolved and dialed on the portal machine, so LAN-only names work — nas.lan:5000, 192.168.1.10:443.

Rejected at validation time: nodes entries that are unknown, repeated, or sit outside a hub region; an entry whose node scope is empty (a topology with no hub nodes at all); a socket the hub node already binds (Reality 443/tcp, the proxy inbound 80/tcp, the metrics listener over TCP, xdns, wireguard and hysteria over UDP — each counted only when that inbound actually renders, so an xdns/wireguard/hysteria block with no user carrying the matching access reserves nothing); and the same port published twice on an overlapping node set. Reservations are per transport, so a tcp publish may reuse the port of a UDP-only listener. The same registry rejects two built-in inbounds on one socket regardless of portals — e.g. hysteria and wireguard both left on 443/udp.

strict¶

strict (default true) confines what traffic emerging from the tunnel may reach on the portal side. The portal config mirrors the declared matchers as direct rules and blackholes the rest:

• one rule for routes.domains and one for routes.ips, copied verbatim from the schema — Xray prefixes such as full:, domain:, regexp: are preserved, so hub and portal cannot disagree about what a matcher means
• one port-pinned rule per publish entry (ip for a literal target, full:<host> for a name), matching only that target's port
• a final catch-all to a blocked blackhole outbound, which is added to the config only when strict is true (by default)

Sniffing on the reverse tunnel is turned off under strict. Xray sniffs with routeOnly, which leaves the dialed address alone but routes on the sniffed SNI/Host instead — an address the client chooses. Every strict matcher would then be evaluated against attacker-supplied text: a published nas.home.arpa:5000 forward would never match its own full:nas.home.arpa rule (the SNI is whatever hostname the client used to reach the hub), while any member could reach an arbitrary LAN host by sending a matching SNI. With sniffing off, the portal matches the destination exactly as the hub sent it. strict: false keeps sniffing on.

With strict: false the portal emits a single catch-all direct rule instead — the pre-strict output — and anything that reaches the {id}-portal outbound can be dialed from the portal machine: its own loopback services, the rest of the LAN, the router's admin interface, the open internet. A hub-side mistake or an over-broad matcher then turns into remote access to the home network.

The portal enforces what, not who. Traffic emerging from a reverse tunnel carries no inbound user, so member filtering stays hub-side and portal-side rules never mention users.

A strict portal uses domainStrategy: IPOnDemand instead of the IPIfNonMatch a non-strict one keeps. IPIfNonMatch only re-runs the rules with DNS when nothing matched, and the strict catch-all always matches on the first pass — so the second pass would never happen and an ip matcher could never cover a domain destination. IPOnDemand resolves inside the first pass, so a domain arriving from the tunnel is still checked against routes.ips.

The hub does no such resolution on your behalf, in either direction. Its rule list ends in a TCP,UDP catch-all (routing.hub_default) that matches everything on the first pass, so the hub's own IPIfNonMatch second pass never runs either. Every ip matcher on the hub — portals[].routes.ips as much as hub_routes[].ips — matches only a destination the client already dialed as an IP literal; routes.ips: [10.0.0.0/8] never catches internal.corp. Declare the name in routes.domains for that.

Two cases then fail closed where a non-strict portal would have dialed:

• The two resolvers disagree. If the hub's DNS lands a name inside a declared CIDR and the portal's DNS does not — split-horizon setups, most often — the connection is blackholed. Declaring the name in routes.domains removes the dependency on DNS entirely, since a domain matcher is checked before any resolution happens.
• The client dialed an IP literal. Hub inbounds sniff with routeOnly: the sniffed SNI/Host decides the route, but the dialed address is left alone, and the address is what the tunnel carries. A client that resolves DNS itself and opens 1.2.3.4:443 with SNI home.alice.example.com matches routes.domains on the hub and enters the tunnel, then arrives at the portal as 1.2.3.4:443 and is blackholed. Clients that send the hostname are unaffected — SOCKS and HTTP proxies do, as do TUN implementations that rewrite the destination from their own sniffing (sing-box, Clash) — but a plain tun2socks-style setup does not. Cover the address range in routes.ips when members connect that way.

strict: false is the escape hatch for both.

Matchers are copied verbatim, so a geosite: / geoip: / ext: entry in routes also lands in the portal config and Xray refuses to start without the matching .dat asset on the portal machine. Keep strict portals on literal matchers, or deploy the asset files there too.

Example:

portals:
  - id: home
    users: [alice, bob]
    routes:
      domains: [internal.example.com, "domain:lan"]
      ips: [10.0.0.0/8, 192.168.1.0/24]
    publish:
      # NAS web UI, reachable only from the office range
      - port: 8443
        target: 192.168.1.10:443
        allow: [203.0.113.7/32, 198.51.100.0/24]
        nodes: [euH00]
      # game server, both transports, every hub node
      - port: 27015
        target: nas.lan:27015
        network: tcp,udp

  - id: lab
    users: [alice]
    routes:
      ips: [172.16.0.0/12]
    # lab names resolve differently on the portal than on the hub
    strict: false

routing¶

ExitRoute¶

HubRoute¶

At least one matcher (domains, ips, users, or proxy_users) is required.

regions¶

type picks the model: exit regions validate as ExitRegion holding ExitNodes, hub regions as HubRegion holding HubNodes. A field of the other kind (vless_route on a hub region, xdns on an exit node) is rejected as an unknown field.

ExitRegion¶

HubRegion¶

LeastLoadSettings¶

RegionRouting (exit regions only)¶

WarpConfig¶

ExitNode¶

HubNode¶

RealityConfig¶

RealityFallbackLimits¶

NodeKeysOverride¶

All fields optional; null means "use the default":

NodeWireguardOverride¶

All fields optional; null means "use the defaults.hub.wireguard value". Set enabled: false to disable WireGuard on this node even when defaults configure it.

HysteriaOverride¶

All fields optional; null means "use the value from the layer below" — defaults.hub.hysteria on hubs, defaults.exit.hysteria → regions[].hysteria on exits (built-in HysteriaConfig defaults when no layer sets a field).

XDNS has no per-node override beyond supplying a full XdnsConfig on the node.

TlsOverride¶

Both fields optional; null means "use the value from defaults.hub.tls". With a Reality default there is nothing to inherit, so certificate is required.

Complete minimal example¶

global:
  namespace: mynet
  aphelion_domain: exit.example.com


defaults:
  exit:
    ipv6: false
    keys:
      auth: mlkem768
      mode: native
      session_time: 600s
  hub:
    ipv6: false
    keys:
      auth: x25519
      mode: native
      session_time: 600s
    exit_connections:
      method: mlkem768x25519plus
    reality:
      dest: www.google.com:443
      xhttp_path: /stream
    xdns:
      domains: [dns.google]
    wireguard:
      subnet: 10.0.0.0/24

groups:
  - id: staff

users:
  - username: alice
    group: staff
    access: [xhttp, cdn, wireguard, xdns]

routing:
  hub_default: exit-nl

regions:
  - id: exit-nl
    type: exit
    vless_route: 1
    nodes:
      - id: nlA00
        hostname: nl-a00.exit.example.com
        reality:
          dest: www.cloudflare.com:443
          xhttp_path: /stream

  - id: hub-eu
    type: hub
    nodes:
      - id: euH00
        hostname: eu-h00.hub.example.com