| name | relay-server-config |
| description | Full environment-variable / flag reference for configuring the portal-tunnel relay-server (cmd/relay-server), plus how config is embedded and how Docker/Compose deploys it. Use when configuring, deploying, or debugging a relay. |
relay-server configuration
Entrypoint cmd/relay-server/main.go, dispatched by utils.RunCommands (""/serve → serve, help). Every flag has an env fallback parsed by utils.{String,Bool,Int}FlagEnv at flag-init time (utils/cmd.go); flags are declared in main.go ~79-117. --help shows usage/examples only, not flags.
Core env vars / flags (default)
| Env | Default | Purpose |
|---|
PORTAL_URL | https://localhost | portal base URL (--portal-url) |
PORTAL_FRONTEND_DIR | empty | custom SPA dir; empty = embedded (--frontend-dir) |
IDENTITY_PATH | ./.portal-certs | identity/cert + policy.json dir (--identity-path) |
API_PORT | 4017 | HTTPS API + frontend (--api-port) |
SNI_PORT | 443 | public SNI ingress (--sni-port) — cannot bind unprivileged; override locally |
WIREGUARD_PORT | 51820 | (--wireguard-port) |
EMBEDDED_DNS_PORT | 53 | embedded authoritative DNS (--embedded-dns-port) — default provider; needs 53/tcp+udp and CAP_NET_BIND_SERVICE in containers |
ADMIN_TOKEN | empty | bearer token for admin/policy APIs (--admin-token) |
LANDING_PAGE_ENABLED | false | (--landing-page-enabled) |
DISCOVERY | false | enable gossip; needs BOOTSTRAPS (--discovery) |
BOOTSTRAPS | empty | comma-separated bootstrap relay URLs (--bootstraps) |
TRUST_PROXY_HEADERS | false | trust XFF etc. (--trust-proxy-headers) |
TRUSTED_PROXY_CIDRS | empty | (--trusted-proxy-cidrs) |
UDP_ENABLED / TCP_ENABLED | false | non-HTTP lease transports |
MIN_PORT / MAX_PORT | 0 / 0 | lease port range; 0 disables |
PPROF_ENABLED / PPROF_ADDR | false / 127.0.0.1:6060 | pprof |
X402_ENABLED / X402_TESTNET / X402_PAY_TO | false / false / empty | mounts facilitator under /api/x402 only when enabled |
Embedded DNS is the default ACME_DNS_PROVIDER (empty value): EMBEDDED_DNS_PORT (default 53). External provider creds remain env-bound: ACME_DNS_PROVIDER, CLOUDFLARE_TOKEN, GCP (GCP_PROJECT_ID+aliases, GCP_MANAGED_ZONE+aliases), Hetzner (HETZNER_API_TOKEN/HCLOUD_TOKEN), AWS Route53 (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN/AWS_REGION→defaults us-east-1 downstream/AWS_HOSTED_ZONE_ID/AWS_DNSSEC_KMS_KEY_ARN), VULTR_API_KEY, NJALLA_TOKEN, ENS_GASLESS_ENABLED (unsupported with embedded). Never hardcode these — reference as env vars / secrets.
Reserved API surface (types/paths.go)
Root-host trees that must never fall through to the SPA: types.ReservedRootPrefixes = /api, /sdk, /discovery, /v1. x402 public paths /x402/prepare, /x402/client.js; relay facilitator /api/x402/{supported,verify,settle}. Discovery: /discovery, /discovery/announce (only when DISCOVERY=true).
Admin/policy API
GET/POST /api/policy with Authorization: Bearer $ADMIN_TOKEN. POST requires the FULL settings object (partial bodies → 400 invalid_mode). Persists to $IDENTITY_PATH/policy.json.
Config embedding & Docker
config.toml (version/protocol) and registry.json (default relays) are embedded via manifest.go and parsed in types/types.go.docker-compose.yml runs ghcr.io/gosuda/portal:2, publishes TCP 443 + TCP/UDP 53 (embedded DNS, cap_add: NET_BIND_SERVICE) + UDP WireGuard port, and passes the above env vars.Dockerfile: Node 22 stage builds the frontend into cmd/relay-server/dist/app, then make build-server-bin compiles the Go relay.
