PORTAL v2

Configuration Reference

Static relay cache

Capability is enabled by default in the relay binary. Exposures are eligible only with portal expose --serve ./dist --cache. Cached responses terminate TLS at the selected relay and lose browser-to-origin end-to-end encryption. Only currently granted friendly aliases use the cache. New canonical <service>.<address>.<relay-root> hostnames are never relay cached, and friendly aliases always use the live origin.

EnvironmentFlagDefaultMeaning
CACHE_ENABLED--cache-enabledtrueEnable origin-opted-in cache admission
CACHE_MAX_BYTES--cache-max-bytes1073741824Relay payload bytes, including staging and pinned evictions
CACHE_MAX_TTL--cache-max-ttl24hMaximum offline TTL added to the bounded lease-liveness deadline

The total byte budget must be positive; TTL must be between 1s and 8760h. The cache manager internally limits each exposure to one quarter of the total budget, capped at 64 MiB and rounded down with a one-byte minimum. Each object is limited to 10 MiB or the exposure limit, whichever is smaller. --cache-ttl on the origin is only a request, clamped by the relay. Cache expiry is min(ExpiresAt, LastSeenAt + 2m) + effective TTL. Unregister may shorten expiry to the unregister time plus that TTL, but cannot extend it. Uploads have a two-minute body-read deadline; manifest checks have an independent admission pool, a 1 MiB body limit, and a ten-second read deadline. The manager allows at most two concurrent uploads and two concurrent checks; these internal limits keep slow checks from consuming upload slots. The cache holds at most 128 snapshots with at most 2,048 files each. Expired snapshots are removed first, then least recently used snapshots. Storage-full, unsupported capability, or upload rejection falls back to the origin tunnel. Storage lives under IDENTITY_PATH/static-cache, which must be exclusive to one relay process. Restart may discard all cached content. Allow additional disk space for filesystem metadata and block allocation beyond the payload limit.

Checking Relay Configuration

This page describes what each variable means. To see the effective relay values inside the bundled container, ask the binary rather than reading a table:

docker compose run --rm -T portal config

It prints every environment key the relay consumes, its effective value and source, and any side-effect-free validation error the server would reject. Compose-only variables, container settings, and external SDK configuration are outside this report.

Run it inside the container, without --env-file. Compose has already combined .env with the defaults declared in docker-compose.yml, so the report then describes the environment docker compose up will actually provide. --env-file reads a file on its own, against the relay binary’s defaults — MIN_PORT is 0 there and 40000 under Compose. Use it to inspect a file in isolation, not to predict the surrounding deployment:

relay-server config                    # this process environment
relay-server config --env-file .env    # one file, against relay defaults

relay-server config --format env regenerates the relay-owned list from the flag definitions, and make check-env-example fails when this page or .env.example stops mentioning a key.

Relay Server Environment Variables

The relay server (relay-server) reads configuration from environment variables. Each variable corresponds to a CLI flag of the same shape (e.g. PORTAL_URL → --portal-url). CLI flags take precedence over environment variables when both are set.

A value that cannot be parsed is a startup error rather than a silent fallback: DISCOVERY=yes fails immediately instead of resolving to false.

Core

VariableDefaultTypeDescription
PORTAL_URLhttps://localhoststringCanonical public HTTPS origin, including the externally reachable port
PORTAL_FRONTEND_DIR""stringCustom SPA directory containing index.html; empty uses the frontend embedded in the Portal binary
IDENTITY_PATH./.portal-certsstringDirectory path for relay identity, policy state, and TLS materials
SNI_PORTPORTAL_URL port, else 443intLocal TCP SNI router listen port; an unset value follows the explicit PORTAL_URL port when it names one, and it never changes the public port advertised from PORTAL_URL

PORTAL_URL owns public semantics and SNI_PORT owns local bind semantics. Portal derives tenant URLs, reverse endpoints, and QUIC connection metadata from PORTAL_URL. An unset SNI_PORT follows the explicit PORTAL_URL port when it names one, so a direct listener on a non-default port needs a single setting:

PORTAL_URL=https://localhost:8443

When a load balancer maps public port 443 to a local listener on 8443, use:

PORTAL_URL=https://relay.example.com
SNI_PORT=8443

Portal does not compare these ports because it cannot infer external NAT or load-balancer topology.

Optional HTTP redirect listener

VariableDefaultTypeDescription
HTTP_REDIRECT_ENABLEDfalseboolEnable the redirect-only listener (--http-redirect-enabled)
HTTP_REDIRECT_ADDR:80stringTCP listen address (--http-redirect-addr); use 127.0.0.1:18080 for local testing
HTTP_REDIRECT_HSTSfalseboolInclude Strict-Transport-Security: max-age=31536000 on redirects (--http-redirect-hsts)

Every request receives 301 Moved Permanently to the normalized configured PORTAL_URL, never to a request Host or forwarded-header destination. Request paths and queries are discarded; this does not implement per-tenant redirects. Existing URL normalization retains a configured base path, removes trailing slashes and the legacy /relay suffix, and drops configured queries/fragments. Enabling redirects requires an explicit absolute HTTPS PORTAL_URL without credentials and with a valid port; HTTPS scheme spelling is case-insensitive. The listen address must use host:port syntax (bracket IPv6 addresses) with a numeric port from 0 to 65535; port 0 requests an automatically assigned port. relay-server config reports validation failures as INVALID <error> and successful validation as OK relay configuration is valid. Validation only checks configuration: it does not resolve listen hosts or bind sockets, so OK is not a readiness check. Bind failures, including occupied ports or unavailable hosts, still fail startup. Keys in an env file that the relay does not read are reported as UNKNOWN with a closest-match suggestion instead of being silently dropped. Disabled mode preserves existing loopback HTTP-to-HTTPS URL normalization. Shutdown releases the listener. The listener uses bounded read, write, and idle timeouts.

Browsers ignore HSTS received over HTTP. This optional insecure-response header does not protect clients or establish HSTS. Effective HSTS must be served over HTTPS by the destination. This option does not change HTTPS or tenant policy and does not add includeSubDomains or preload.

relay-server --portal-url https://localhost:14443 --sni-port 14443 --http-redirect-enabled --http-redirect-addr 127.0.0.1:18080
curl -i -H "Host: untrusted.example" "http://127.0.0.1:18080/ignored?secret=value"

For bundled Compose, set HTTP_REDIRECT_ENABLED=true, retain HTTP_REDIRECT_ADDR=:80, and add "80:80" to the portal service’s ports. Changing the container listen port also requires changing this mapping. Open TCP 80 in the firewall; binding privileged ports may require OS permissions.

Transport

VariableDefaultTypeDescription
MIN_PORT0intInclusive minimum port for UDP and raw TCP transports (0 = disabled)
MAX_PORT0intInclusive maximum port for UDP and raw TCP transports (0 = disabled)
UDP_ENABLEDfalseboolEnable UDP relay transport; requires a valid MIN_PORT/MAX_PORT range
TCP_ENABLEDfalseboolEnable raw TCP port transport; requires a valid MIN_PORT/MAX_PORT range

Features

VariableDefaultTypeDescription
DISCOVERYfalseboolServe relay discovery endpoints and poll discovery peers
BOOTSTRAPS""stringAdditional bootstrap relay API URLs used for discovery expansion (comma-separated)
IVNP_CONFIG""pathOptional IVNP RouterConfig JSON file; enables the IVNP overlay and requires DISCOVERY=true; empty disables the overlay
APPROVAL_MODEautostringInitial lease approval mode (auto | manual). A mode saved in policy.json wins; see Private relay
DEFAULT_IDENTITY_BPS1048576intStream bytes/second per service identity without an individual admin override (--default-identity-bps); shared across all connections and both directions; 0 is unlimited
UNAPPROVED_LEASES_PER_SOURCE64intPer-source unapproved lease or pending request budget (0 disables the per-source limit); see Private relay
TUNNEL_SOURCE_CIDRS""stringNetworks that may register tunnels (comma-separated CIDRs); a tunnel from anywhere else gets 403 source_not_allowed; empty allows every network, and a value that names no network is a startup error; see Accept tunnels only from your networks

TUNNEL_SOURCE_CIDRS limits tunnel registration and renewal, not discovery announces. With DISCOVERY=true, announces share the global pre-auth budget with registration and can delay registrations from allowed networks. Keep discovery disabled on a restricted relay unless needed; see Discovery and registration capacity for the effect and limits of budget tuning.

IVNP overlay

IVNP_CONFIG now points to a JSON object using the fields of IVNP’s RouterConfig, defined in the pinned revision’s config.go; newer IVNP revisions dropped the API.md document that used to describe it. Portal applies the file to ivnp.DefaultRouterConfig() and lets IVNP validate the resulting configuration. An existing file containing {} enables the overlay with IVNP’s defaults: in-memory router state and a transient service destination. Unknown fields, invalid values, and legacy ivnp.conf syntax fail startup; replace the old file explicitly when upgrading. Runtime Logger and Resolver collaborators cannot be configured through this file.

This file configures IVNP’s router; Portal applies it, while IVNP owns destination reachability and path topology. See IVNP-backed overlay networking for the ownership boundary and the architecture for the protocol flow.

For explicit router persistence, mount a private writable directory and use:

{
  "Persistence": { "Directory": "/var/lib/portal/ivnp-router" }
}

Relative persistence paths resolve from the relay process working directory. Use a dedicated embedded-router directory; an old daemon state directory with named application destinations is incompatible and must not be reused. Persistence preserves router state only. Portal creates a transient destination on each start and republishes its new address through relay discovery.

Other JSON fields use the upstream Go types: addresses such as NTCP2.Bind are "0.0.0.0:0" strings, and durations are integer nanoseconds. Nested fields not supplied keep IVNP defaults; disabling a transport requires zeroing all its fields as required by IVNP validation. Portal uses ivnp.DefaultDestinationConfig() for its service; tunnel construction and internal routing remain IVNP-owned.

Local router configuration and socket setup happen during startup. Destination creation waits for tunnels and confirmed publication in the background, while public ingress and direct reverse transport remain available. Shutdown explicitly closes the router and its destination resources, including pending connections.

Payments

VariableDefaultTypeDescription
X402_ENABLEDfalseboolEnable relay-owned Sui x402 facilitator endpoints under /api/x402 for future control-plane payments
X402_TESTNETfalseboolUse Sui testnet for relay-owned x402 facilitator payments; false uses Sui mainnet
X402_PAY_TO""stringSui payment recipient address for relay-owned control-plane x402 resources; required (non-empty) when X402_ENABLED=true

Proxy

VariableDefaultTypeDescription
TRUST_PROXY_HEADERSfalseboolTrust X-Forwarded-* and X-Real-IP headers from trusted proxies
TRUSTED_PROXY_CIDRS""stringExplicit trusted proxy CIDR allowlist for forwarded headers (comma-separated); empty trusts no proxies and uses socket addresses even with TRUST_PROXY_HEADERS=true

When upgrading a deployment that used TRUST_PROXY_HEADERS=true with an empty TRUSTED_PROXY_CIDRS, set the proxy’s fixed address explicitly (/32 for IPv4, /128 for IPv6). Private and loopback addresses are no longer trusted implicitly. Without an allowlist, source limits apply to the socket peer, which is the proxy when one sits in front. The trusted proxy must overwrite X-Forwarded-For and X-Real-IP with the client address; see the reverse-proxy trust boundary.

TLS

VariableDefaultTypeDescription
TENANT_CERTIFICATESfalseboolOpt into tenant CSR issuance with the relay ACME account and DNS provider. Public issuance requires an existing relay ACME account key, an explicitly approved service identity, and shared durable budget state. Relays serving operator-managed certificate files without a relay ACME account key do not offer automatic tenant issuance. Auto-mode registration alone is not an issuance grant. Local development CAs are exempt from approval and public quota accounting.
TENANT_ISSUANCE_STATE_DIR(empty)stringRequired for public tenant issuance: operator-created shared durable directory with coherent operating-system file locks across all relay instances consuming the same CA quota. Startup rejects missing state or a journal that cannot be opened for reading and writing. Unavailable state suppresses issuance capability. Corrupt, locked, or full state fails closed during issuance; an active order does not disable the capability. Local development issuance requires no public quota state.
ACME_CA_DIR_URL""stringOptional ACME CA directory URL (https) for managed certificate issuance; empty defaults to Let’s Encrypt production. Account registrations and managed certificates are stored per directory: Let’s Encrypt production keeps fullchain.pem and privatekey.pem, while other CAs use fullchain-<id>.pem and privatekey-<id>.pem. Switching back reuses that CA’s saved state. A private CA can be trusted with lego’s LEGO_CA_CERTIFICATES PEM file path (mount the file in Docker). See GTS setup for an EAB-required CA.
ACME_EAB_KID""stringExternal Account Binding key ID for new ACME accounts. Provide together with ACME_EAB_HMAC when the CA requires EAB or you want to bind a new account. Existing CA-specific registrations are reused without EAB credentials.
ACME_EAB_HMAC""secretBase64url HMAC secret paired with ACME_EAB_KID. Unpadded and padded URL encoding are accepted by lego. Credentials are checked when registering a new account; missing, incomplete, malformed, or rejected credentials fail registration without CA fallback. Both EAB values are redacted from config reports.
ACME_DNS_PROVIDER""stringDNS provider for managed DNS-01 challenges, A/AAAA sync, and ENS gasless DNSSEC/TXT automation (embedded | cloudflare | gcloud | hetzner | njalla | route53 | vultr); unset defaults to embedded; valid manual fullchain.pem/privatekey.pem in IDENTITY_PATH overrides issuance only when neither acme-account.key nor acme-registration.json exists
PUBLIC_IPS""stringThe relay’s public IPv4 and/or IPv6 address for A/AAAA records, comma-separated, at most one per family; empty discovers them from outbound connections. When set, the list replaces discovery for both families; see IPv4 and IPv6
ENS_GASLESS_ENABLEDfalseboolEnable ENS gasless DNS import automation for a public relay domain and lease hostnames through the selected DNS provider. With embedded, local records are signed and the operator publishes the DS at the parent zone; Cloudflare, Google Cloud DNS, Route53, and Vultr use their provider APIs. Hetzner and Njalla do not support ENS DNSSEC automation

ACME cancellation is cooperative, not an end-to-end issuance deadline. ACME HTTP requests and DNS provider publication use the operation context, including provider API requests and change-status polling. Providers retain their configured TTL, propagation, polling, HTTP timeout, zone, and credential options.

Each order keeps the TXT record’s original CNAME target and its exact value for cleanup. Existing matching values and unrelated TXT records are preserved. After cancellation, cleanup uses fresh request and credential contexts with a shared 30-second API/context budget starting at the first cleanup attempt. This is not a strict wall-clock bound for an operator-configured AWS credential_process: its SDK timeout is capped when the client is constructed, but the command may start later and the SDK waits for local process completion. Commands or descendant processes that do not terminate promptly can extend that wait. Google external-account executable credentials also depend on local process termination after cancellation. Nested AWS credential caches can finish internal refresh work after a caller returns; their network requests retain operation cancellation and cannot resume DNS publication. The issuance lock remains held until the provider calls and cleanup return. Portal does not detach an issuance worker to run alongside another order.

Cleanup is best effort, not a guarantee that a remote record was removed. A provider can accept a write but lose its response, or complete it after a canceled request. Cleanup failures produce an ACME warning; lego does not automatically retry them. After a provider outage or cleanup warning, inspect the original challenge target and remove only the stale challenge value, preserving other TXT values.

DNS propagation stops between probes, and idle polling sleeps are capped at five seconds. Lego’s CNAME resolution, in-flight DNS probes, and ACME authorization polling still have context-free stages. DNS exchanges allow 10 seconds on Unix or 20 seconds on Windows, with additional exchanges for TCP fallback, CNAME chains, zone discovery, and multiple nameservers. These stages can still delay other tenant orders and relay renewal after cancellation. Tenant issuance remains disabled by default. The same cancellation and cleanup behavior applies to relay certificates without shortening the configured propagation budget.

Scheduled relay certificate renewal gives the ARI lookup a separate two-minute budget. The certificate order itself uses the provider’s configured propagation timeout and the existing HTTP request timeouts, rather than sharing the two-minute DNS synchronization limit. Relay shutdown still cancels the order.

IPv4 and IPv6

Managed DNS discovers public IPv4 and IPv6 independently and publishes A and AAAA records for the families it finds. One available family is sufficient for address initialization. Apex, wildcard, and tracked ENS hostname updates affect only the supplied family; a transient discovery failure leaves the other family’s existing records intact. Permanently retiring a family requires removing its external DNS records and parent glue; a failed probe is not a request to withdraw them. Explicit ENS hostname cleanup removes both A and AAAA records on external providers. Embedded DNS continues its zone-wide address synthesis and removes the hostname’s ENS TXT association.

Discovery finds the address of the relay’s outbound connections. Set PUBLIC_IPS when clients reach the relay on another address, such as a cloud load balancer, a NAT gateway, a floating IP, or a DNAT rule, or when the relay cannot reach the discovery services. List at most one IPv4 and one IPv6 address. The list is authoritative for both families: the relay publishes exactly these addresses for the apex, the wildcard, and tracked ENS hostnames, and sends no discovery requests. A family left out is neither discovered nor published. Embedded DNS stops answering for it after the restart; external providers keep that family’s existing records, so remove them by hand when you drop a family. Entries must be bare IP addresses. Unspecified, loopback, link-local, and multicast addresses are rejected; private and special-use addresses start with a warning. The relay reads the list at startup, so a change needs a restart, and it logs the addresses it publishes with source=PUBLIC_IPS or source=discovery.

IPv6-only and dual-stack relays require reachable published addresses. Public address discovery observes outbound connections; it does not prove that clients can reach the relay through host, container, or network firewalls. Allow the relay’s public TCP port, the public UDP port when QUIC is enabled, and configured raw TCP/UDP ranges for every family you publish. Embedded DNS also needs 53/tcp and 53/udp on those families. Clients must share a reachable address family with the relay; Portal does not add address translation or multi-hop routing between disconnected IPv4 and IPv6 networks.

With a manual certificate and embedded DNS, startup continues when neither public address family can be discovered. Address initialization is deferred and retries are scheduled. With PUBLIC_IPS, the addresses are known at startup and nothing is deferred. Existing addresses remain available during later discovery failures. Errors applying DNS updates still propagate. Manual certificates with an external provider bypass automatic apex/wildcard address management; manage those records separately. Opt-in ENS automation still uses the selected provider.

Embedded DNS

This section is the canonical reference for embedded DNS configuration. The deployment and self-hosting guides link here rather than restating the details.

Serves the relay base domain from an authoritative DNS server embedded in the relay process, so no DNS provider API credentials are required. It is the default provider when ACME_DNS_PROVIDER is unset. Delegate the base domain once at the parent zone (NS portal.example.com -> ns.portal.example.com with glue A and/or AAAA pointing at reachable relay addresses) and open 53/tcp + 53/udp for each published family. Containers running without root need CAP_NET_BIND_SERVICE to bind the default port. A and AAAA answers for the apex and every covered name are synthesized from PUBLIC_IPS, or from the independently discovered relay addresses when it is unset; ACME DNS-01 TXT records are served directly. DNSSEC signing is always enabled; ENS TXT automation remains opt-in with ENS_GASLESS_ENABLED=true.

The relay automatically generates a single ECDSA P-256 CSK (DNSSEC algorithm 13) in IDENTITY_PATH/dnssec-csk.json. Preserve and back up this file with the identity volume across restarts, container replacement, and migration: deleting or replacing it changes the DNSKEY and breaks validation against an existing parent DS. Portal uses Go’s standard filesystem operations; on Unix a new key is created with mode 0600 and directories created by Portal use mode 0700. Existing operator-provided directories and key files are loaded without ownership, mode, or ACL policy checks and are not modified. Securing the identity volume, including its Windows ACLs, is the operator’s responsibility. Malformed keys and keys for another zone still fail startup rather than triggering automatic replacement.

The signing store must permit the required create, read, write, sync, and rename operations. Filesystem failures fail startup with the underlying operation error without replacing an existing key.

After NS/glue delegation is reachable, copy the ds_record from the relay startup log into a DS record at the parent zone for the delegated domain. EnsureDNSSEC() exports the same full DS record (SHA-256 digest, digest type 2); with ENS enabled it is also exposed in ENS status. Configure the key tag, algorithm, digest type, and digest exactly as exported. Parent DS publication is manual. The embedded provider reports pending even while signing locally: Portal does not authenticate the parent chain, so ens.verified remains false even after you publish the DS. The parent must itself have a valid DNSSEC chain to a trust anchor for public validation. Verify delegation and signatures before publishing the DS, and never publish the CSK private file. Losing the key requires coordinated parent DS replacement; automatic rollover is not implemented.

Authoritative RRsets, including apex DNSKEY and denial-of-existence NSEC records, are signed. Signatures last 24 hours, tolerate five minutes of clock skew, and refresh before answering after 12 hours; keep the host clock synchronized. A finite wildcard zone preserves synthesized addresses even below explicit TXT owners and their ancestors. Before either public address is initialized, missing names return REFUSED without an SOA so resolvers do not negatively cache pending tunnel names. After address initialization, genuinely absent names return authenticated NXDOMAIN. Existing owners without the requested type return NODATA, including AAAA queries on an IPv4-only zone and A queries on an IPv6-only zone. DNSSEC records accompany responses only when requested with EDNS DO (or queried directly), and large UDP responses require TCP retry.

External managed providers (cloudflare, gcloud, hetzner, njalla, route53, vultr) are supported first-class backends; embedded remains the canonical default. Keep any vendor as the parent DNS provider and delegate only the relay subdomain to embedded DNS. Manual/external certificate ownership remains supported via fullchain.pem and privatekey.pem when neither ACME state file is present. Certificate loading itself needs no vendor API credentials, and the embedded provider needs none for DNS management. Managed certificates use the selected external provider for DNS publication. With ENS_GASLESS_ENABLED=true, ENS/DNSSEC synchronization also uses that provider before certificate loading; a manual certificate does not bypass ENS provider credentials.

For Local TLS leases on external managed DNS, reserve the exact service hostname and its address-only parent under the relay root for Portal-managed A/AAAA records. Do not provision unrelated address records at these names. The exact parent preserves legacy address-only URLs when a child suppresses wildcard DNS answers. Regardless of ENS configuration, Portal publishes the parent before the canonical child and waits for provider acknowledgment before starting tenant DNS-01. The parent remains owned while any sibling canonical service or legacy lease needs it, and failed child removal retains the parent for retry. ENS TXT publication remains opt-in. Provider propagation is not atomic across resolvers; a failed cleanup may still require manual removal of the stale challenge TXT record.

VariableDefaultTypeDescription
EMBEDDED_DNS_PORT53intListen port for the embedded authoritative DNS server (UDP and TCP)

Diagnostics

VariableDefaultTypeDescription
PPROF_ENABLEDfalseboolEnable the relay pprof diagnostics HTTP server
PPROF_ADDR127.0.0.1:6060stringpprof listen address when enabled; keep it on loopback unless the port is protected
PPROF_PORT6060intHost port published for the pprof listener, read by Docker Compose rather than the relay. Only takes effect when the matching port mapping in docker-compose.yml is uncommented, which exposes it to the host

Admin

VariableDefaultTypeDescription
ADMIN_TOKENstringBearer token source for relay admin and policy APIs; set a long random value for production relays

Cloudflare

VariableDefaultTypeDescription
CLOUDFLARE_TOKENstringCloudflare DNS API token; required when ACME_DNS_PROVIDER=cloudflare

Google Cloud

VariableAliasesDefaultTypeDescription
GCP_PROJECT_IDGOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, GCE_PROJECTstringGoogle Cloud project ID for Cloud DNS automation; auto-detected from ADC or GCE metadata when omitted
GCP_MANAGED_ZONEGCP_ZONE, GCE_ZONE_IDstringExplicit Google Cloud DNS managed zone name or numeric ID override
GOOGLE_APPLICATION_CREDENTIALSstringPath to GCP service account key file (standard ADC; used by the GCP client library)

Hetzner

VariableAliasesDefaultTypeDescription
HETZNER_API_TOKENHCLOUD_TOKENstringHetzner Cloud API token for DNS automation; required when ACME_DNS_PROVIDER=hetzner

AWS

VariableAliasesDefaultTypeDescription
AWS_ACCESS_KEY_IDstringAWS access key ID for Route53 static credentials; uses the default AWS credential chain when omitted
AWS_SECRET_ACCESS_KEYstringAWS secret access key for Route53 static credentials
AWS_SESSION_TOKENstringAWS session token for Route53 temporary credentials
AWS_REGIONAWS_DEFAULT_REGIONus-east-1stringAWS region for Route53 and Route53-backed DNS-01
AWS_HOSTED_ZONE_IDstringExplicit Route53 hosted zone ID override
AWS_DNSSEC_KMS_KEY_ARNstringAWS KMS key ARN used to create a Route53 DNSSEC key-signing key when needed

Vultr

VariableDefaultTypeDescription
VULTR_API_KEYstringVultr API key for DNS automation; required when ACME_DNS_PROVIDER=vultr

Njalla

VariableDefaultTypeDescription
NJALLA_TOKENstringNjalla API token for DNS automation; required when ACME_DNS_PROVIDER=njalla

Portal Tunnel CLI Flags

The portal expose subcommand accepts the following flags. Flags that read from environment variables are noted in the Env Var column.

Connection

FlagEnv VarTypeDefaultDescription
--relaysstring(registry)Additional Portal relay server API URLs (comma-separated; scheme omitted defaults to https)
--discoverybooltrueInclude public registry relays and discover additional relay bootstraps
--max-active-relaysMAX_ACTIVE_RELAYSint3Maximum auto-selected relays to keep connected; explicit relays are always included
--overlayOVERLAY_ENABLEDboolfalsePrefer an IVNP overlay path when available; retains direct fallback
--ban-mitmBAN_MITMboolfalseBan relay when the MITM self-probe detects TLS termination

Identity

FlagEnv VarTypeDefaultDescription
--identity-pathIDENTITY_PATHstringidentity.jsonIdentity JSON file path
--identity-jsonIDENTITY_JSONstringIn-memory identity JSON; takes precedence over --identity-path without reading or writing that file

Lease

Tunnel-owned TLS flags and their defaults are listed in the CLI reference. Automatic mode uses --tls-auto and persistent --tls-state-dir; manual mode uses --tls-cert plus --tls-key. The Local TLS agent example below lists the corresponding TOML keys and relative-path rules. Public automatic issuance also needs the relay’s TENANT_CERTIFICATES, explicit service approval, and TENANT_ISSUANCE_STATE_DIR; see issuance admission.

FlagEnv VarTypeDefaultDescription
--namestringSelect a service and request its friendly alias; up to 63 ASCII characters after normalization. Overrides a legacy saved name without rewriting the signing identity
--descriptionstringService description metadata
--tagsstringService tags metadata (comma-separated)
--ownerstringService owner metadata
--thumbnailstringService thumbnail URL metadata
--hideboolfalseHide service from relay listing screens
--authstringProtect the complete HTTP application with siwe, credential, oidc, saml, or email; excludes cache, TCP, and UDP
--auth-allowstringAllowed principal for siwe (Ethereum wallet) or credential (subject); repeatable; empty allows any valid principal; oidc and saml also read it, as --auth-email-list; requires --auth
--auth-email-liststringWho may sign in with oidc or saml (verified email, @example.com domain, or sub:<subject>) or email (email or @example.com domain); repeatable; at least one entry is required; requires --auth
--auth-oidc-issuerAUTH_OIDC_ISSUERstringOIDC issuer URL for --auth oidc
--auth-oidc-client-idAUTH_OIDC_CLIENT_IDstringOIDC client ID for --auth oidc
--auth-oidc-client-secretAUTH_OIDC_CLIENT_SECRETstringOptional OIDC client secret for --auth oidc
--auth-saml-metadata-urlAUTH_SAML_METADATA_URLstringSAML identity provider metadata URL for --auth saml
--auth-saml-metadata-fileAUTH_SAML_METADATA_FILEstringSAML identity provider metadata file, instead of the URL, for --auth saml
--auth-saml-entity-idAUTH_SAML_ENTITY_IDstringhttps://<host>/_portal/auth/saml/metadataSAML service provider entity ID for --auth saml
--auth-saml-subject-attributeAUTH_SAML_SUBJECT_ATTRIBUTEstringNameIDSAML attribute that names the visitor for --auth saml
--auth-smtp-addrAUTH_SMTP_ADDRstringSMTP server host:port for --auth email; port 465 uses TLS from the start, other ports must offer STARTTLS, and only localhost, 127.0.0.1 or ::1 may use plaintext
--auth-smtp-usernameAUTH_SMTP_USERNAMEstringSMTP username for --auth email; set together with the password
--auth-smtp-passwordAUTH_SMTP_PASSWORDstringSMTP password for --auth email, with spaces around it dropped; pass it by environment variable
--auth-smtp-fromAUTH_SMTP_FROMstringFixed sender address of every login link for --auth email
--auth-identity-headersboolfalseInject verified X-Portal-User and X-Portal-Auth upstream headers; requires --auth
--auth-identity-proofAUTH_IDENTITY_PROOFstringSecret sent as X-Portal-Proof with the identity headers; at least 16 visible ASCII characters; requires --auth-identity-headers; set it by environment variable, not on the command line, because process lists show arguments
--strip-request-headerstringClient request header removed before routed HTTP forwards it upstream; repeatable; case-insensitive, and the underscore spelling of a name (X_Custom for X-Custom) goes with it; applies to HTTP and WebSocket upgrades; Host and X-Forwarded-Proto cannot be stripped (always regenerated before this middleware runs); X-Forwarded-Prefix and X-Portal-User/Auth/Proof are allowed; requires --http-route, --target, or --auth
--x402-pay-tostringPayment recipient address for this tunnel
--x402-testnetboolfalseUse Sui testnet when --x402-network is omitted
--x402-networkstringOptional Sui, Casper, or Nano CAIP-2 network
--x402-assetstringwCSPR CEP-18 contract hash required by Casper
--x402-endpointstringOptional Sui RPC, Casper facilitator, or Nano RPC endpoint; repeatable
--x402-facilitator-tokenCSPR_CLOUD_API_KEYstringCasper facilitator authorization token

Routing

FlagEnv VarTypeDefaultDescription
--http-routestringHTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:PAYMENT_AMOUNT] form; repeat to aggregate multiple local HTTP services behind one public URL; route amounts require --x402-pay-to

Static Sites

FlagTypeDefaultDescription
--servestringServe a directory or HTML file with SPA fallback; excludes positional target, --http-route, --tcp, and --udp
--cacheboolfalseAllow selected relays to store --serve content and terminate browser TLS; excludes --ban-mitm
--cache-ttlduration0Offline TTL request; requires --cache; 0 uses relay policy, otherwise 1s to 8760h, clamped by the relay

These options have no environment-variable fallback and are not agent TOML fields. See static serving.

Diagnostics

FlagTypeDefaultDescription
--metrics-addrstringemptyOptional host:port serving Prometheus /metrics; no environment fallback

Transport

FlagEnv VarTypeDefaultDescription
--udpUDP_ENABLEDboolfalseEnable public UDP relay in addition to the default stream path
--udp-addrUDP_ADDRstringLocal UDP target address for relayed datagrams (host:port or port only); defaults to the target when --udp is enabled
--tcpTCP_ENABLEDboolfalseRequest a dedicated TCP port on the relay for raw TCP services (no TLS; e.g., Minecraft, game servers)

The portal list subcommand accepts the following flags:

FlagTypeDefaultDescription
--relaysstring(registry)Additional Portal relay server API URLs (comma-separated)
--default-relaysbooltrueInclude public registry relays

Configuration Files

config.toml

portal agent run reads the platform default config.toml and starts one managed process for all declared tunnels. Relative paths are resolved from the config file directory. The config file must exist before the agent is started.

Default paths:

OSConfigDefault identity
Linux user$XDG_CONFIG_HOME/portal-tunnel/agent/config.toml or ~/.config/portal-tunnel/agent/config.toml$XDG_DATA_HOME/portal-tunnel/agent/identity.json or ~/.local/share/portal-tunnel/agent/identity.json
Linux root/etc/portal-tunnel/agent/config.toml/var/lib/portal-tunnel/agent/identity.json
macOS user~/Library/Application Support/Portal Tunnel/Agent/config.toml~/Library/Application Support/Portal Tunnel/Agent/identity.json
macOS root/Library/Application Support/Portal Tunnel/Agent/config.toml/Library/Application Support/Portal Tunnel/Agent/identity.json
Windows%ProgramData%\Portal Tunnel\Agent\config.toml%ProgramData%\Portal Tunnel\Agent\identity.json
[agent]
control_addr = "127.0.0.1:4018"
service_name = "portal-agent"

[[tunnels]]
id = "web"
name = "myapp"
target = "127.0.0.1:3000"
relays = ["https://portal.example.com"]
discovery = false
overlay = true
description = "Managed web tunnel"
tags = ["web"]
auth = "siwe"
auth_allowed_wallets = ["0x1234..."]
auth_identity_headers = true

[[tunnels]]
id = "api"
name = "myapp"
x402_pay_to = "0x..."
x402_testnet = true

[[tunnels.http_routes]]
prefix = "/api"
upstream = "http://127.0.0.1:3001"
methods = ["GET"]
amount = "0.01"

[[tunnels.http_routes]]
prefix = "/"
upstream = "http://127.0.0.1:5173"

Portal-native credential authentication is an alternative to SIWE and can optionally restrict allowed credential subjects with auth_allowed_wallets for immediate per-subject revocation:

[[tunnels]]
id = "credential-web"
name = "credential-app"
target = "127.0.0.1:3000"
auth = "credential"
auth_allowed_wallets = ["alice"]
auth_identity_headers = true

--auth-allow / auth_allowed_wallets is the list for siwe and credential. --auth-email-list / auth_email_list is the list for oidc, saml, and email: a tunnel runs one provider, so the one list serves all three. oidc and saml still read --auth-allow / auth_allowed_wallets, so existing configs keep working. Setting both keys is refused. email takes only --auth-email-list.

Agent fields:

FieldDefaultDescription
state_dirPlatform default state directoryStores the local control endpoint token and runtime state
control_addr127.0.0.1:4018Loopback-only local control API address
service_nameportal-agentOS service name
allowed_walletsemptyWallet addresses allowed to read local agent status through wallet auth; empty allows any wallet on the loopback auth endpoint

The local agent dashboard and mutating control API calls use the bearer token in the agent state directory. Wallet-authenticated agent requests are read-only and can only read /agent/status.

Supported tunnel fields follow the corresponding portal expose options. The agent supports serve for static sites. It does not support cache or cache_ttl:

FieldTypeDescription
idstringStable tunnel ID used by the agent dashboard
namestringSelects this service under the signing key, overriding any legacy saved name without rewriting the identity file; omitted uses the saved name or an unnamed service
max_active_relaysintAuto-selected relay limit; defaults to 3; explicit relays remain included
ban_mitmboolBan on suspected TLS termination; defaults to warning-only
targetstringLocal TCP target, equivalent to the portal expose <target> argument
http_routestable arrayHTTP route mappings; cannot be combined with target, serve, tcp, or udp
servestringStatic site directory or HTML file, relative to the config file’s directory; cannot be combined with target, http_routes, tcp, or udp. Directories use index.html; unknown paths fall back to the entry file, which must exist when the tunnel starts
relaysstring arrayExplicit relay API URLs
discoveryboolInclude registry and relay discovery expansion; defaults to true
overlayboolPrefer an IVNP overlay path when available; defaults to direct and retains direct fallback
identity_pathstringTunnel identity JSON file path. When omitted, one tunnel uses the platform default identity.json; multiple tunnels use <state-dir>/<tunnel-id>/identity.json
identity_jsonstringIn-memory identity JSON; takes precedence over identity_path without reading or writing that file
tls_autoboolObtain and renew exact canonical certificates through the relay; defaults to false
tls_state_dirstringAutomatic certificate/key directory; requires tls_auto; defaults to resolved identity_path plus .tls; must be explicit with identity_json
tls_require_localboolRequire namespace support and, in automatic mode, usable canonical readiness; defaults to false; requires automatic or manual Local TLS; manual mode already rejects legacy-only relays
tls_cert, tls_keystringManual certificate-chain and matching private-key PEM files; supply both; cannot be combined with tls_auto
tls_monitor_state_dirstringOpt into warning-only CT/CAA observations and persist public evidence; omitted disables monitoring
tls_monitor_baselinestringOperator-maintained CAA/SPKI baseline JSON; requires tls_monitor_state_dir; omitted leaves CAA unconfigured
tls_monitor_dns_resolverstringIndependent DNS resolver IP:port; requires tls_monitor_state_dir; defaults to 1.1.1.1:53 when monitoring is enabled
udp, udp_addr, tcpbool/stringUDP and raw TCP relay options
description, tags, owner, thumbnail, hidemixedLease metadata shown by relays
authstringApplication login provider: siwe, credential, oidc, saml, or email; cannot be combined with TCP or UDP
auth_allowed_walletsstring arrayPrincipals allowed to sign in with siwe (Ethereum wallets) or credential (subjects); empty allows any valid principal; oidc and saml also read it, as auth_email_list; requires auth when set
auth_email_liststring arrayWho may sign in with oidc or saml (verified emails, @example.com domains, or sub: subjects) or email (emails and @example.com domains); at least one entry is required; requires auth when set
auth_oidc_issuerstringOIDC issuer URL; required when auth = "oidc"
auth_oidc_client_idstringOIDC client ID; required when auth = "oidc"
auth_oidc_client_secretstringOptional OIDC client secret for auth = "oidc"
auth_saml_metadata_urlstringSAML identity provider metadata URL; auth = "saml" needs it or auth_saml_metadata_file
auth_saml_metadata_filestringSAML identity provider metadata file, relative to the config file
auth_saml_entity_idstringSAML service provider entity ID; defaults to the metadata URL of each host
auth_saml_subject_attributestringSAML attribute that names the visitor; defaults to the NameID
auth_smtp_addrstringSMTP server host:port; required when auth = "email"
auth_smtp_usernamestringSMTP username for auth = "email"; set together with the password
auth_smtp_passwordstringSMTP password for auth = "email"
auth_smtp_fromstringFixed sender address of every login link; required when auth = "email"
auth_identity_headersboolInject verified Portal identity headers upstream; requires auth
strip_request_headersstring arrayClient request headers removed before routed HTTP forwards them upstream; case-insensitive; Host and X-Forwarded-Proto cannot be listed (always regenerated); X-Portal-User/Auth conflict with auth_identity_headers; requires http_routes or a target
x402_pay_tostringPayment recipient for paid HTTP routes
x402_testnetboolUse Sui testnet when x402_network is omitted; omitted or false uses Sui mainnet
x402_networkstringOptional CAIP-2 network: sui:mainnet, sui:testnet, casper:casper, casper:casper-test, or nano:mainnet
x402_assetstringwCSPR CEP-18 contract hash; required for Casper payments
x402_endpointsstring arrayOptional Sui RPC endpoints, Casper facilitator URL, or Nano RPC nodes; Casper uses the first endpoint, Nano requires at least two
x402_facilitator_tokenstringCasper facilitator authorization token; when omitted, the agent uses CSPR_CLOUD_API_KEY
x402_optionstable of stringsNetwork-specific options passed to the x402-facilitator paywall unchanged, such as nano_claims_file; an option the network does not support stops the tunnel
http_routes[].amountstringOptional human payment amount, such as 0.01, for one HTTP route prefix; requires x402_pay_to
http_routes[].methodsstring arrayOptional HTTP methods that require payment on that route; empty means every method

When the agent saves config.toml, it writes the values that were set and leaves out the defaults that were not. For example, an omitted discovery, ban_mitm, or max_active_relays stays out of the file, and an explicit discovery = false stays in it. The agent always writes id and identity_path, because they name the tunnel and its identity. Each value must have the type that the table gives: the agent refuses max_active_relays = "3".

When any routed HTTP entry has amount, the tunnel also serves /x402/client.js and /x402/prepare on the public tunnel origin. Browser frontends served by another route in the same tunnel can import /x402/client.js and use x402Fetch() for Sui payments. Casper clients read the 402 requirements from the protected resource, sign them with a compatible external SDK, and retry with PAYMENT-SIGNATURE or X-PAYMENT; the embedded browser client remains Sui-only. Payment is enforced by the tunnel before the request reaches the upstream.

The tunnel does not implement any payment network itself. It passes the x402_* settings to the resource/paywall package of x402-facilitator, which validates the network, pay-to, asset and amounts, settles payments, and owns network state such as Nano claim logs. A network the facilitator adds is usable here after a dependency update.

x402 payment networks

NetworkAssetDecimalsFacilitator
sui:mainnet, sui:testnetUSDC gasless stablecoin6Built-in Sui facilitator
casper:casper, casper:casper-testwCSPR CEP-18 token9https://x402-facilitator.cspr.cloud, overridable per payment
nano:mainnetXNO native coin30Built-in Nano facilitator reading public RPC nodes

Casper has no Go chain SDK, so casper:* payments delegate /verify and /settle to a remote x402 facilitator over HTTP. The wCSPR CEP-18 contract hash differs per network deployment, so it must be set as the payment asset. The default CSPR.cloud facilitator requires an access token in CSPR_CLOUD_API_KEY; use x402_facilitator_token only when the agent service cannot receive that environment variable.

x402_network = "casper:casper-test"
x402_asset = "hash-..."
x402_pay_to = "account-hash-..."
x402_endpoints = ["https://x402-facilitator.cspr.cloud"]

Nano payers broadcast their own send block and pay with its block hash (payload.blockHash). The tunnel confirms the block on every configured RPC node (at least two; the facilitator’s public nodes when x402_endpoints is omitted), requires a confirmed send of exactly the route amount to x402_pay_to, and accepts each block hash once per tunnel process. The route amount is in XNO and is published in raw units (1 XNO = 10^30 raw). Nano has no memo field, so use a dedicated pay-to account for each paid tunnel.

Two Nano options close the remaining gaps:

  • nano_claims_file: keeps accepted block hashes refused after a restart. Each hash is appended and synced to the file (mode 0600) before the request is served, and a file with an unreadable line stops the tunnel. Use an absolute path and one file per tunnel; the tunnel closes it when it stops.
  • nano_require_binding = "true": a block hash is public once broadcast, so this accepts a payment only when the payer also signs it with the key of the account that sent the block, over the extra.binding nonce and resource published in the route’s 402 (nano-block-sig/1).
x402_network = "nano:mainnet"
x402_pay_to = "nano_..."
x402_endpoints = ["https://rpc.nano.to", "https://rainstorm.city/api"]
x402_options = { nano_claims_file = "/var/lib/portal/nano-claims.jsonl", nano_require_binding = "true" }

For a task-oriented walkthrough, see Portal Agent.

Local TLS services

All TLS file, state-directory, and monitor-baseline paths above resolve relative to config.toml. Automatic and manual Local TLS select the negotiated <service>.<address>.<relay-root> namespace. Canonical handshakes require usable local material; friendly URLs retain their separate Keyless policy. Local TLS cannot be combined with raw TCP or UDP in the agent HTTP path. Monitoring cannot be combined with raw TCP; the agent does not support relay cache.

Two services can share a signing identity while retaining separate leases, targets, and per-hostname leaf keys:

[[tunnels]]
id = "blog"
name = "blog"
target = "3000"
identity_path = "identity.json"
tls_auto = true
tls_require_local = true

[[tunnels]]
id = "api"
name = "api"
target = "4000"
identity_path = "identity.json"
tls_auto = true
tls_require_local = true

Explicit names do not rewrite the shared identity file. Automatic mode requires relay operator issuance admission; it persists and reuses each hostname’s key across restart and renewal. Protect and back up this state. Deleting it loses the leaf key and can require a new CA order. Without tls_require_local, older relays may still provide friendly aliases. Canonical certificate failure never changes that hostname to Keyless.

For manual mode, set tls_cert and tls_key instead of tls_auto and tls_state_dir. Only the exact assigned canonical DNS SAN is allowed. Missing, expired, corrupt, mismatched, wildcard, or sibling-SAN material is rejected. Successful checks reload replaced files at most hourly during lease renewal; restart for immediate reload. An invalid replacement leaves the previous usable pair installed, but expiry still withdraws canonical readiness. Manual mode does not issue or automatically renew certificates.

See CLI Local TLS for hostname and migration rules, and certificate monitoring for the optional baseline, evidence format, and observation limits.

identity.json

Stores the secp256k1 identity used to sign tunnel sessions and relay descriptors. portal expose treats --identity-path as a direct JSON file path. relay-server treats IDENTITY_PATH as a state directory and stores this file at IDENTITY_PATH/identity.json.

FieldTypeDescription
namestringOptional legacy service-name default; new tunnel identity files omit it, and an explicit service name overrides it without rewriting the file
addressstringDerived EVM address used for SIWE and identity ownership
public_keystringCompressed secp256k1 public key hex
private_keystringsecp256k1 private key hex; keep secret
mnemonicstringBIP-39 mnemonic used to derive the secp256k1 identity key; keep secret
derivation_pathstringEVM derivation path for mnemonic; defaults to m/44'/60'/0'/0/0

The file or --identity-json supplies the signing key. Explicit --name or agent name selects a service without changing the persisted identity. Omitting the name retains an old file’s saved default; new files store no service name. Distinct explicit service names can share one key and retain independent leases and targets. Use a separate identity path when a different signing key is wanted. See Identity Names for friendly, Local TLS, and legacy canonical hostnames and the reserved unnamed-service label.

When mnemonic is present, Portal derives the private key at derivation_path and preserves the mnemonic form when rewriting identity.json. The same identity file or state directory can be reused across restarts to keep a stable address.

policy.json

Persists relay policy state. Managed automatically by the relay on write; do not edit manually while the server is running.

Relay policy settings are stored at IDENTITY_PATH/policy.json.


ACME DNS Provider Configuration

Set ACME_DNS_PROVIDER (or --acme-dns-provider) to one of the values below to enable DNS-backed automation. Portal uses the same provider for DNS-01 challenges, managed A/AAAA records, and optional ENS gasless DNS records.

An empty value selects embedded, the canonical managed backend; see Embedded DNS for NS/glue delegation, DS setup, and persistent signing-key requirements. The external providers below are supported first-class backends. Valid manually supplied fullchain.pem and privatekey.pem files in IDENTITY_PATH take precedence over managed certificate issuance only when neither acme-account.key nor acme-registration.json exists, regardless of provider selection. If either ACME state file remains, Portal treats the PEM files as managed certificate material. Manual overrides do not disable embedded A/AAAA serving or opt-in ENS automation through the selected provider.

For ENS gasless behavior and wallet authentication details, see Wallet and ENS.

Cloudflare (cloudflare)

VariableRequiredDescription
CLOUDFLARE_TOKENYesCloudflare DNS API token with Zone:DNS:Edit permission

Google Cloud DNS (gcloud)

VariableRequiredDescription
GCP_PROJECT_IDNoGoogle Cloud project ID; auto-detected from ADC or GCE metadata when omitted
GCP_MANAGED_ZONENoCloud DNS managed zone name or numeric ID; inferred from the portal domain when omitted
GOOGLE_APPLICATION_CREDENTIALSNoPath to a service account key JSON file; uses Application Default Credentials when omitted

AWS Route53 (route53)

VariableRequiredDescription
AWS_ACCESS_KEY_IDNoAccess key ID; uses the default AWS credential chain (instance profile, env, ~/.aws/credentials) when omitted
AWS_SECRET_ACCESS_KEYNoSecret access key; required when AWS_ACCESS_KEY_ID is set
AWS_SESSION_TOKENNoSession token for temporary credentials
AWS_REGIONNoAWS region; defaults to us-east-1
AWS_HOSTED_ZONE_IDNoRoute53 hosted zone ID; inferred from the portal domain when omitted
AWS_DNSSEC_KMS_KEY_ARNNoKMS key ARN for DNSSEC key-signing key creation

Hetzner DNS (hetzner)

VariableRequiredDescription
HETZNER_API_TOKENYesHetzner Cloud API token with DNS zone and RRSet write access

Note: Hetzner DNS does not support provider-side DNSSEC signing, so ACME_DNS_PROVIDER=hetzner supports ACME and A/AAAA records, but not ENS gasless DNSSEC automation.

Njalla DNS (njalla)

VariableRequiredDescription
NJALLA_TOKENYesNjalla API token with DNS record write access

Note: Njalla supports managed ACME, A/AAAA records, and TXT records. Portal does not automate Njalla DNSSEC signing, so ACME_DNS_PROVIDER=njalla does not support ENS gasless DNSSEC automation.

Vultr DNS (vultr)

VariableRequiredDescription
VULTR_API_KEYYesVultr API key with DNS domain, record, and DNSSEC write access

Pre-auth admission

Registration challenges, registration attempts, and discovery announces share one weighted source-IP budget and one relay-wide budget. These limits run before signature verification; verified lease operations use identity policy instead. IP addresses are never durable moderation identities.

Environment variableDefaultMeaning
PREAUTH_SOURCE_PER_MINUTE10Source-IP units refilled per minute
PREAUTH_SOURCE_BURST100Source-IP burst capacity
PREAUTH_GLOBAL_PER_MINUTE600Relay-wide units refilled per minute
PREAUTH_GLOBAL_BURST200Relay-wide burst capacity
PREAUTH_CHALLENGE_COST1Units per registration challenge
PREAUTH_ANNOUNCE_COST2Units per discovery announce
PREAUTH_REGISTER_COST5Units per registration attempt

Positive values are required; zero selects the default. Both burst capacities must cover the largest endpoint cost. The source burst allows 16 complete challenge-plus-registration flows from one IP, accommodating concurrent startups behind a shared NAT or TCP proxy. Those clients still share a source bucket, refilled at 10 units per minute by default; this does not restore original client IPs. The global default allows approximately 100 complete challenge-plus-registration flows per minute, with a burst of 33. This is an initial operational budget, not a measured capacity guarantee: tune it to relay resources and observed rejection rates.

Rejected requests return HTTP 429 and Retry-After. Update tunnels/SDKs to v2.4.3 alongside the relay: the SDK treats admission limits as temporary, honors retry guidance, and retains a valid signed registration challenge across retries. Source buckets expire after 30 minutes idle, are collected on subsequent traffic, and have a hard ceiling of 65,536 entries. Invalid signatures incur no additional penalty. IPv6 buckets use individual addresses.

Since v2.4.3, startup explicitly removes legacy banned_ips from policy.json. Identity approvals, denials, bans, and bandwidth settings are preserved. Operators requiring network IP blocks should configure their firewall or trusted ingress proxy.

Upstream request-header trust contract

Portal’s HTTP tunnel forwards client request headers to upstream applications almost unchanged. It always regenerates X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto from the observed request, so client-supplied copies are replaced. X-Forwarded-Prefix is deleted on every request and only re-added for non-root routes; root-route upstreams never see a client-supplied value. Client-supplied X-Portal-User, X-Portal-Auth, and X-Portal-Access-Credential headers are always stripped by the HTTP gateway; X-Portal-User and X-Portal-Auth are only injected after verified login when --auth-identity-headers is enabled. X-Portal-Proof is handled the same way and is only sent when --auth-identity-proof is set (see Verifying the identity headers).

Any other header an Internet client sends arrives at the upstream verbatim.

Upstream applications must not trust arbitrary request headers as proof of identity. If the upstream runs behind another reverse proxy or VPN that sets identity headers (for example Tailscale-User-Login, X-Remote-User, or X-Real-IP), a Portal visitor can trivially forge them. Use --strip-request-header (repeatable, case-insensitive) to remove such headers before they reach the upstream:

portal expose 127.0.0.1:3000   --strip-request-header Tailscale-User-Login   --strip-request-header X-Remote-User

--strip-request-header works with --http-route, --target, or --auth. It cannot be combined with --serve because static sites do not proxy request headers. Host and X-Forwarded-Proto are always regenerated before this middleware runs and cannot be suppressed through this option. X-Forwarded-For and X-Forwarded-Host are regenerated downstream by the reverse proxy, so stripping them here is safe and has no lasting effect.

The same policy applies automatically to WebSocket upgrade requests routed through --http-route. Portal-owned forwarding headers are set after stripping, so they remain correct and trusted.

Public tenant issuance admission

Explicit approval through the existing operator policy is required even in automatic registration mode. A fresh identity, lease, IP address, or CSR does not grant CA access. Denied, banned, expired, and replaced leases remain ineligible. Request shedding before authentication protects CPU and request processing only; it is not CA quota protection. Durable issuance reservations happen only after live lease authentication, operator approval, ownership, and CSR validation.

TENANT_ISSUANCE_STATE_DIR/tenant-orders.jsonl is an append-only, fsynced journal protected by an operating-system exclusive file lock, released when the process exits. Every reservation is durable before an ACME client can place an order. Failures, cancellations, incomplete replies, and crash-ambiguous orders consume capacity for the full rolling seven-day window. Success appends validated public certificate validity dates; it never refunds a reservation. Corrupt or truncated state fails closed instead of resetting quotas.

The conservative ceilings are 20 new attempts and 10 eligible renewal attempts per registered domain and CA directory in seven days, 40 total attempts per CA directory, and three attempts per exact hostname, with a one-hour hostname cooldown. Subdomains share their public-suffix-derived registered-domain bucket. A recorded successful, unexpired certificate reaching two thirds of its lifetime qualifies for the separate renewal capacity. A new CSR or key alone does not qualify, and renewals still consume total CA and hostname capacity. This is local admission, not a claim of exemption from any CA’s renewal or duplicate-certificate rules.

All replicas, including replicas with different ACME accounts or base subdomains, must point at the same pre-existing, durably provisioned, lock-coherent directory. Independent local disks are not a supported shared-quota deployment. Do not delete, truncate, restore an older copy of, or rotate this journal to recover capacity. The 16 MiB journal ceiling requires operator maintenance that preserves reservations and successful issuance history; there is no automatic reset. Filesystem locking and durable writes must work across the deployment. Operators must reserve additional quota for relay certificates and other issuers outside this endpoint and keep tenant issuance disabled if their CA’s limits or external consumption leave insufficient headroom. No filesystem-local mechanism coordinates independent installations.