HexRift

Config generator for the Conglomerate distributed proxy network. Takes a topology definition and produces Xray JSON configs and HAProxy configs for every node. Hub nodes additionally support WireGuard and XDNS inbounds.

[!WARNING] HexRift is in active development. Until the v1.0.0 release, the CLI, topology schema, and generated config output may change at any time — breaking changes can land in any release, including patch versions. Pin an exact version (e.g. hexrift==0.8.0) and check the release notes before upgrading.

Installation

uv sync

Usage

All commands require a topology YAML file:

hexrift --yaml conglomerate.yaml <command>

Commands

Examples

# Validate topology
hexrift validate

# Visualize topology
hexrift show

# Show all derived identifiers
hexrift derive all

# List all exit node IDs (for scripts)
hexrift nodes list --names --type exit

# Structured node list (id, hostname, region, type) for other tools
hexrift nodes list --json

# Add a node to the topology file (creates the region if needed)
hexrift nodes add nlA20 --reality-dest www.samsung.com:443 --reality-xhttp-path /login/

# Generate keys for all nodes
hexrift gen-keys --all

# Build Xray config for a specific node
hexrift build nlA00 --xray --out-dir ./out

# Build all configs (Xray + HAProxy)
hexrift build --all --xray --haproxy --out-dir ./out

# Diff against deployed config
hexrift diff nlA00 --current-dir /etc/xray

# Generate a share link (CDN URL)
hexrift share alice --cdn

# Generate share links for all guests of a user
hexrift share alice --all-guests --bare | clip

# Generate a WireGuard client config
hexrift share alice --wg

Topology options

Beyond the basic hub/exit split:

• HAProxy-less nodes - by default every node runs HAProxy on :443 in front of Xray. Set haproxy: false to drop HAProxy and have Xray's Reality inbound bind 0.0.0.0:443 (or [::]:443 when ipv6 is supported) directly. build --haproxy then emits a no-op stub haproxy.cfg so managed HAProxy service stays up without touching :443. CDN (cdn_xhttp_path) needs HAProxy TLS termination and cannot be combined with haproxy: false.
• All-in-one node - set routing.hub_default: direct to make a hub egress everything itself (direct outbound) instead of routing to exit region. This allows topology with hub node(s) and no exit regions - single node clients connect to that proxies straight to the internet. hub_routes still apply for per-domain/user exceptions.
• Hysteria 2 - defaults.hub.hysteria: (or a node-level hysteria:) adds a QUIC/UDP inbound for users with access: [hysteria]; hexrift share USER --hy2 prints the hysteria2:// URL. An exit region with protocol: hysteria is dialed by hubs over Hysteria instead of VLESS+Reality (tuning via defaults.exit.hysteria → regions[].hysteria → nodes[].hysteria); an exit that defines hysteria on the region/node serves the listener regardless of protocol, so switching a region's protocol only redeploys hub configs. Hysteria needs a real TLS cert: by default HexRift derives a self-signed leaf from the node's Reality key (key_type: ed25519, or ecdsa-p256) and pins it (hub outbounds via pinnedPeerCertSha256, share URLs via pinSHA256); set certificate: {cert_file, key_file} + sni to serve an operator-issued cert instead. Xray's Hysteria dialer parrots Chrome's QUIC ClientHello, which cannot negotiate Ed25519 certs, so hubs dialing an ed25519 exit set disableChromeParrot; a hysteria2:// URL has no such switch, so hub listeners that Xray-based client apps dial should use ecdsa-p256. UDP ports must not collide with wireguard/xdns on the same hub. See Topology Schema.
• Site-to-site portals - portals: declares a machine (e.g. a home server) that dials the hubs and opens a reverse tunnel; hub traffic from the portal's member users that matches routes egresses there. publish: forwards a hub-bound port into the tunnel for the ingress direction - that port is unauthenticated internet ingress and ignores portals[].users, so set allow. strict: true (the default) confines portal-side egress to the declared routes/publish matchers and blackholes the rest. See Topology Schema.

Architecture

hexrift/
  components/
    schema/     # Pydantic models for yaml
    derive/     # Identity derivation (UUIDs, shortIds, emails), defaults resolution,
                # topology->Xray-fragment construction, WireGuard and Hysteria derivation
    keys/       # x25519 + ML-KEM 768 keypair generation and storage
    render/     # Xray config builder + HAProxy Jinja2 templates
  core/         # BaseApplication / Component / Controller framework
  inbounds/     # Pluggable inbound specs (xhttp, cdn, proxy, xdns, wireguard, hysteria) + node contexts
  links/        # Pluggable hub→exit link protocols (vless+reality, hysteria): dial context + outbound
  shared/       # Cross-component helpers (crypto encoding, Xray/xhttp/hysteria fragments)
  templates/    # Jinja2 stubs
    haproxy/
    wireguard/

Derivation

All identifiers are deterministically derived from the topology:

• NAMESPACE UUID = UUID5(UUID(0), namespace)
• User UUID = UUID5(NAMESPACE_UUID, username)
• Server UUID = UUID5(USER_UUID, {username}-server)
• Portal UUID = UUID5(NAMESPACE_UUID, portal/{id})
• Guest UUID = UUID5(USER_UUID, {label})
• Hub-exit UUID = UUID5(NAMESPACE_UUID, {hubId}-{exitId})
• Warp UUID = Hub-exit UUID with 3rd segment replaced by ffff
• Group shortId = SHA256{groupId}.{namespace}
• Hub shortId = SHA256{nodeId}.hub.{namespace}
• Exit shortId = SHA256{nodeId}.exit.{namespace}
• WireGuard keypair = x25519(HMAC-SHA256(reality_private_key, {identity_uuid}.wireguard.{namespace}))
• Hysteria certificate = self-signed leaf for the SNI; key seed = HMAC-SHA256(reality_private_key, hysteria-tls.{namespace}) for ed25519, hysteria-tls-ecdsa-p256.{namespace} for ecdsa-p256; the pin is SHA-256 of its DER
• Hysteria obfs password = base64url(HMAC-SHA256(reality_private_key, hysteria-obfs.{namespace}))

Keys

Keypairs are stored in keys/{nodeId}.yaml. Hub nodes in the same region share the same keypair. Key strings follow the format:

• Decryption (server inbound): {method}.{mode}.{session_time}[.{padding}].{PRIVATE_KEY_b64}
• Encryption (client outbound): {method}.{mode}.0rtt.{PUBLIC_KEY_b64}