PORTAL v2

CLI Reference

The portal CLI exposes local services through Portal relay servers. The relay provides transport and routing. The tunnel process decides whether a connection is handled as the default HTTPS stream, routed HTTP, raw TCP, or UDP.

Install

macOS / Linux

curl -fsSL https://github.com/gosuda/portal-tunnel/releases/latest/download/install.sh | bash

Windows PowerShell

$ProgressPreference = 'SilentlyContinue';
irm https://github.com/gosuda/portal-tunnel/releases/latest/download/install.ps1 | iex;

From A Relay

If your relay publishes its own installer:

curl -sSL https://portal.example.com/api/install.sh | bash

The installer downloads the portal binary and adds it to your PATH. It does not create a config file.

Command Overview

CommandPurpose
portal exposeExpose one local service or one routed HTTP bundle
portal auth issueIssue a Portal-native application access credential
portal listPrint relay URLs resolved for this invocation
portal agentRun a durable local multi-tunnel agent
portal updateReplace the CLI with the latest release
portal versionPrint the current version

portal expose

Common workflows:

portal expose 3000
portal expose 3000 --auth siwe
portal expose --serve ./dist
portal expose localhost:25565 --tcp

Expose a local service with optional flags:

portal expose [flags] <target>

Or run routed HTTP mode:

portal expose [flags] --http-route "PATH=UPSTREAM [METHOD[,METHOD...]:PAYMENT_AMOUNT]" [...]

The payment suffix is optional; omit it for free routes.

Target Formats

FormatExampleResolves to
Bare port3000127.0.0.1:3000
Host and portlocalhost:8080localhost:8080
URL hosthttp://127.0.0.1:3000127.0.0.1:3000

URL inputs are accepted for address parsing. Paths, queries, and fragments are not supported.

Mode Selection

ModeExampleNotes
Default HTTPS streamportal expose 3000Relay routes by SNI; tunnel process terminates tenant TLS
Static siteportal expose --serve ./distServes a directory or an HTML file with SPA fallback
Routed HTTPportal expose --http-route /api=3001 --http-route /=5173Tunnel process runs the HTTP reverse proxy
Dedicated raw TCPportal expose localhost:25565 --tcpRelay allocates a public TCP port
UDP relayportal expose 8080 --udp --udp-addr 19132Relay allocates a public UDP port

Flags

portal expose --help (or portal help expose) lists common flags first, then advanced flags for metadata, provider settings, and operations. Both groups are accepted in the same command; advanced flags do not require a configuration file.

Common Flags

FlagTypeDefaultDescription
--namestringSelect this service under the signing identity and request its friendly alias; one normalized DNS label, at most 63 ASCII characters. Overrides a legacy saved name without rewriting the identity file
--relaysstringregistryAdditional relay API URLs, comma-separated
--discoverybooltrueInclude registry relays and relay discovery expansion
--overlayboolfalsePrefer an IVNP overlay path when available; retains direct fallback
--http-routestringHTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:PAYMENT_AMOUNT] form; repeatable; route amounts require --x402-pay-to
--servestringServe a local directory or HTML file; unknown paths fall back to the entry HTML
--tcpboolfalseRequest a dedicated raw TCP port on the relay
--replicaboolfalseJoin HTTP replicas sharing one service identity key and URL; requires a supporting relay; excludes dedicated TCP/UDP ports, relay cache, overlay, email/SAML authentication, and Nano payments
--udpboolfalseEnable public UDP relay in addition to the default stream path
--authstringProtect HTTP application access with siwe, credential, oidc, saml, or email; cannot be combined with --cache
--auth-allowstringPrincipal allowed to sign in with siwe (Ethereum wallet) or credential (subject); repeat for multiple principals (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); repeat for multiple entries (at least one entry is required); requires --auth
--auth-oidc-issuerstringOIDC issuer URL for --auth oidc (env: AUTH_OIDC_ISSUER)
--auth-oidc-client-idstringOIDC client ID for --auth oidc (env: AUTH_OIDC_CLIENT_ID)
--auth-oidc-client-secretstringOptional OIDC client secret for --auth oidc (env: AUTH_OIDC_CLIENT_SECRET)
--auth-saml-metadata-urlstringSAML identity provider metadata URL for --auth saml (env: AUTH_SAML_METADATA_URL)
--auth-saml-metadata-filestringSAML identity provider metadata file, instead of the URL, for --auth saml (env: AUTH_SAML_METADATA_FILE)
--auth-saml-entity-idstringhttps://<host>/_portal/auth/saml/metadataSAML service provider entity ID for --auth saml (env: AUTH_SAML_ENTITY_ID)
--auth-saml-subject-attributestringNameIDSAML attribute that names the visitor for --auth saml, such as email (env: AUTH_SAML_SUBJECT_ATTRIBUTE)
--auth-smtp-addrstringSMTP server host:port that sends the login links for --auth email; port 465 uses TLS from the start, any other port must offer STARTTLS, and only localhost, 127.0.0.1 or ::1 may use plaintext (env: AUTH_SMTP_ADDR)
--auth-smtp-usernamestringSMTP username for --auth email; set it together with the password, or leave both empty for a server that needs no login (env: AUTH_SMTP_USERNAME)
--auth-smtp-passwordstringSMTP password for --auth email, with spaces around it dropped; pass it by environment variable, because process lists show arguments (env: AUTH_SMTP_PASSWORD)
--auth-smtp-fromstringThe one sender address of every login link for --auth email, with an optional display name (env: AUTH_SMTP_FROM)
--x402-pay-tostringPayment recipient address for this tunnel
--ban-mitmboolfalseBan relay when the MITM self-probe detects TLS termination
--identity-pathstringidentity.jsonIdentity JSON file path; created automatically when missing

Advanced Flags

FlagTypeDefaultDescription
--tls-autoboolfalseObtain and renew exact canonical certificates through an approved relay; enables the Local TLS service namespace
--tls-state-dirpathidentity path plus .tlsPersistent automatic certificate/key storage; requires --tls-auto; must be explicit with --identity-json
--tls-require-localboolfalseRequire namespace support; in automatic mode also require usable canonical readiness. Requires automatic or manual Local TLS; manual mode already rejects legacy-only relays
--tls-certpathManual certificate chain PEM; requires --tls-key; only the exact service canonical DNS SAN is allowed
--tls-keypathMatching manual private key PEM; requires --tls-cert
--tls-monitor-state-dirpathdisabledOpt into evaluation-only, warning-only certificate monitoring; persist evidence and send hostname queries to independent DNS and CertSpotter
--tls-monitor-baselinepathunconfiguredOperator-managed CAA/SPKI baseline JSON; requires --tls-monitor-state-dir
--tls-monitor-dns-resolverIP:port1.1.1.1:53 when enabledResolver for monitoring; requires --tls-monitor-state-dir; bracket IPv6 addresses
--max-active-relaysint3Maximum auto-selected relays to keep connected; explicit relays are always included
--identity-jsonstringIn-memory identity JSON; takes precedence over --identity-path without reading or writing that file
--descriptionstringService description metadata
--tagsstringService tags metadata, comma-separated
--thumbnailstringService thumbnail URL metadata
--ownerstringService owner metadata
--hideboolfalseHide service from relay listing screens
--auth-identity-headersboolfalseSend authenticated X-Portal-User and X-Portal-Auth headers to HTTP upstreams; requires --auth
--auth-identity-proofstringSecret sent as X-Portal-Proof with the identity headers so the upstream can verify they came from Portal; at least 16 visible ASCII characters; requires --auth-identity-headers; pass it by environment variable, not on the command line, because process lists show arguments (env: AUTH_IDENTITY_PROOF)
--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-tokenstringCSPR_CLOUD_API_KEYCasper facilitator authorization token; prefer the environment variable so the secret is not exposed in the process arguments
--x402-optionstringNetwork-specific option in KEY=VALUE form passed to the x402-facilitator paywall, such as nano_claims_file=/var/lib/portal/claims.jsonl or nano_require_binding=true; repeatable; an unsupported option is an error
--strip-request-headerstringClient request header removed before routed HTTP forwards it upstream; repeatable; case-insensitive; applies to HTTP and WebSocket upgrades; Portal-owned headers (Host, X-Forwarded-*) are always rewritten after stripping; requires --http-route or --auth
--cacheboolfalseOpt in to relay storage and browser TLS termination for --serve
--cache-ttlduration0Requested offline cache lifetime; 0 uses relay policy; requires --cache
--log-formatstringtextLog output format; json sends application log records as one structured JSON record per line on stdout for machine integration; top-level command errors stay on stderr (see Machine-Readable Relay Lifecycle)
--exit-on-stdin-eofboolfalseBind the tunnel lifetime to a caller-owned stdin pipe or socket; closing its last writer requests normal shutdown
--udp-addrstringLocal UDP target; defaults to the primary target when --udp is enabled
--metrics-addrstringOptional host:port for Prometheus /metrics

IVNP-backed overlay networking

portal expose 3000 --overlay

This asks the relay to prefer an available overlay gateway for reverse streams. Portal selects and authorizes the endpoints; IVNP owns the gateway-to-ingress path. Direct reverse transport remains the default and fallback. See the overlay networking concepts for why endpoint policy and network routing are separate, and the architecture for the protocol.

Identity Names

The identity file supplies the reusable signing key. An explicit --name selects a service without rewriting that file, including when the file already exists or the key comes from --identity-json. New identity files store no service name. When the option is omitted, a legacy file’s saved name remains the compatibility default; otherwise the service is unnamed. Use distinct explicit names to serve independent targets under one signing key.

For example, repeat --name blog when restarting a service with a newly created identity file:

portal expose 3000 --identity-path ./identity.json --name blog
# On later runs, keep --name blog to select the same service.
portal expose 3000 --identity-path ./identity.json --name blog

Omitting --name on the later run selects the unnamed service because the new file stores only the key identity. This changes the URL even though the signing key is unchanged.

EndpointHostnameTLS and cache policy
Friendly alias, if granted<name>.<relay-root>Live Keyless; explicit opt-in relay static cache
Local TLS canonical<service>.<40-lowercase-hex-address>.<relay-root>Exact tunnel-owned certificate; never relay cached

Local TLS uses reserved default for an unnamed service. A canonical URL does not depend on receiving an alias. Old one-label canonical URLs are removed; there are no redirects. Unnamed HTTP services need Local TLS. Clients requiring the removed URLs must upgrade; alias-capable older clients retain live aliases.

Tunnel-owned Local TLS

portal expose 3000 --name blog --identity-path identity.json 
  --tls-auto --tls-require-local

Automatic issuance needs a relay with tenant issuance enabled and, for public CA orders, explicit approval for this service plus shared durable issuance budget state. See relay configuration. Without --tls-require-local, an older relay may still provide a friendly alias, and a compatible relay’s alias can become ready while canonical issuance is pending. The new canonical hostname itself never falls back to Keyless.

Certificate/key bundles persist per hostname in --tls-state-dir, defaulting to the identity file path plus .tls. With --identity-json, supply this directory explicitly. Renewals reuse the stored leaf key. Issuance failure keeps a still-valid certificate; expiry withdraws canonical readiness and rejects new canonical TLS handshakes. Friendly endpoints stay separate.

For manual material, replace --tls-auto with --tls-cert chain.pem --tls-key key.pem. Files must form a currently valid pair with exactly the assigned canonical hostname as the only DNS SAN, without wildcard or sibling identities. Pin the intended relay with --relays <url> --discovery=false. Files reload during lease certificate checks, at most hourly after a successful check; restart for immediate reload. Invalid replacements retain the previous usable pair. Manual mode does not obtain or automatically renew certificates.

Moving to a new canonical is an explicit origin migration: update links, callbacks, allowed origins, cookies, and browser storage as appropriate. There is no automatic redirect. Legacy canonical URLs have been removed without redirects. Local key ownership does not remove the relay’s DNS issuance authority or give ordinary browser JavaScript native exporter verification; see the security model.

Constraints

  • Automatic and manual Local TLS cannot be combined, and neither can be used with raw TCP or UDP in the CLI/agent HTTP path.
  • --tls-state-dir requires --tls-auto. --tls-require-local requires --tls-auto or a complete manual certificate/key pair; manual mode already rejects legacy-only relays.
  • Certificate monitoring requires --tls-monitor-state-dir; its baseline and resolver options alone are invalid. Monitoring cannot be used with raw TCP, relay static cache, or browser/WASM exposures.
  • Choose one of <target>, --serve, or --http-route.
  • --serve cannot be combined with --tcp or --udp.
  • --cache requires --serve and cannot be combined with --ban-mitm.
  • --cache-ttl requires --cache; a nonzero value must be between 1s and 8760h and is clamped by the relay.
  • --http-route cannot be combined with --tcp or --udp.
  • --strip-request-header requires --http-route or --auth; it applies to every routed HTTP upstream, including WebSocket upgrades, and Portal-owned headers (Host, X-Forwarded-*) cannot be removed by it.
  • --tcp and --udp require matching transport support on the relay.
  • Route payment amounts are part of --http-route and require a tunnel-owned --x402-pay-to.
  • Tunnel paid routes use Sui mainnet by default. Casper requires an explicit --x402-network casper:... and --x402-asset; it uses the hosted facilitator by default or the first --x402-endpoint override. The default CSPR.cloud facilitator also requires CSPR_CLOUD_API_KEY. Nano requires --x402-network nano:mainnet and a nano_ pay-to address; repeat --x402-endpoint for at least two RPC nodes or omit it for the public defaults. --x402-option nano_claims_file=PATH keeps spent blocks spent across restarts, and --x402-option nano_require_binding=true requires a payer signature.

Application-Owned Tunnel Lifetime

Applications launching Portal as a subprocess can own its lifetime through a stdin pipe:

portal expose --http-route /=7317 --identity-path ./portal-identity.json 
  --exit-on-stdin-eof --log-format json

Create the child with piped stdin and keep its writer open while the tunnel is desired. Pipes and Unix sockets are accepted, including the socketpair that Node.js child_process uses for stdio: 'pipe'. Portal drains and ignores bytes; stdin is not a command protocol. A terminal, regular file, or null device is rejected when this flag is enabled. Without the flag, stdin does not control the tunnel’s lifetime.

Closing the last writer requests the same cancellation and cleanup as a normal shutdown signal, including best-effort relay unregister and listener closure. This applies during startup, after readiness, and while reconnecting or failed. Cancellation during startup exits successfully. An unexpected stdin read error also requests shutdown and logs a warning. Existing shutdown timeouts apply; unregister has a five-second timeout per relay, not a five-second process deadline. Shutdown errors remain visible as a nonzero exit status. For example, if the relay is offline, unregister may fail even though EOF successfully stops the tunnel.

Normal application exit or a forced kill closes its pipe handles. This stops Portal only if no other process retains a writer: prevent writer inheritance and close unused copies. This is pipe ownership, not universal parent-death detection. Continue draining stdout and stderr and observing subprocess exit. Use the existing JSON relay lifecycle records below for readiness, and retract advertised URLs when the subprocess exits.

The application owns restart policy, authorization, and identity persistence through the existing identity options. Its access checks and header filtering remain its responsibility. Cleanup of older unmanaged processes may still be needed during migration.

Use portal agent for durable tunnels whose lifetime Portal and the OS service manager own. Use this option when the calling application owns the tunnel’s lifetime; it adds no daemon or control API.

Machine-Readable Relay Lifecycle

Integrations that launch portal expose as a subprocess can track relay readiness without parsing human-facing messages:

portal expose 3000 --log-format json
GuaranteeBehavior
RecordsOne structured JSON log record per line on stdout; filter by "event":"relay_status"
Human outputUnchanged by default; --log-format text (default) keeps the human-readable console
State ownershipRecords are emitted from the same authoritative SDK status paths the human logs derive from
TransitionsRecords report readiness, readiness loss (ready → connecting), the relay refusing the lease, failures, and deselection; repeated unchanged statuses are omitted

One ready record:

{"level":"info","event":"relay_status","relay_url":"https://relay.example.com","state":"ready","public_url":"https://myapp-<identity>.relay.example.com","alias_url":"https://myapp.relay.example.com","deselected":false,"time":"2026-01-01T00:00:00Z","message":"service ready at https://myapp-<identity>.relay.example.com (short URL: https://myapp.relay.example.com)"}

Fields on event=relay_status records:

FieldMeaning
eventAlways relay_status
relay_urlRelay API URL this status describes
stateconnecting, ready, or failed
failurePresent when state is failed: runtime (recoverable), terminal, or mitm (TLS termination detected; requires --ban-mitm)
approvalPresent while the relay refuses this lease: pending (not approved yet) or refused (denied or banned). state is connecting and public_url is empty. Its absence does not mean approved
public_urlIdentity-bound canonical URL; usable only when nonempty and state is ready. Local TLS keeps it empty before usable material exists and withdraws it on expiry
legacy_urlSeparate one-label canonical compatibility URL for a Local TLS lease; use only while state is ready and not deselected
alias_urlShort <name>.<relay-domain> URL without an Ethereum address; prefer this for sharing when present. Present only while state is ready and granted: a failed, deselected, or address-only relay never reports one
deselectedtrue on the removal notification for a relay that left the membership set; a previously advertised relay URL must be retracted

Records never carry access tokens, private identities, or other secrets; other log levels and messages on the same stream are not part of this contract. A consumer needing an authoritative complete membership snapshot should use the SDK’s Relays(), not the lossy event stream.

A connecting record retracts readiness until a subsequent ready record, and never reports an alias_url. For Local TLS, a ready record may have an empty public_url and a usable legacy_url or alias_url. Retract a previously advertised canonical when a later record empties public_url, even if state remains ready for the separate compatibility endpoint.

On a manual relay, a waiting tunnel logs waiting for relay approval once, not on every retry, and needs no restart after approval:

{"level":"warn","event":"relay_status","relay_url":"https://relay.example.com","state":"connecting","public_url":"","deselected":false,"approval":"pending","address":"0x...","time":"2026-01-01T00:00:00Z","message":"waiting for relay approval"}

Raw TCP and UDP tunnels log raw transport endpoints allocated once a reverse stream opens, so the line also means that the relay accepts the lease.

Examples

Expose a local web app:

portal expose 3000

Protect the app with tunnel-local SIWE login:

portal expose 3000 --auth siwe
# Restrict login and pass the verified identity to the upstream.
portal expose 3000 --auth siwe --auth-allow 0x1234... --auth-identity-headers

Protect it without requiring a browser wallet, then issue a host-scoped credential from the tunnel identity:

portal expose 3000 --auth credential
portal auth issue myapp.example.com --subject alice --expires 720h

Protect it with a standard OpenID Connect provider (see OpenID Connect):

portal expose 3000 --auth oidc 
  --auth-oidc-issuer https://accounts.google.com 
  --auth-oidc-client-id <client-id> 
  --auth-email-list alice@example.com

--auth-email-list is required with --auth oidc. The AUTH_OIDC_* variables are read only with --auth oidc, so exporting them for one service does not affect another portal expose. An --auth-oidc-* flag given on the command line without --auth oidc is rejected.

Protect it with a SAML 2.0 identity provider (see SAML 2.0):

portal expose 3000 --auth saml 
  --auth-saml-metadata-url https://idp.example.com/realms/main/protocol/saml/descriptor 
  --auth-email-list @example.com

--auth-email-list is required with --auth saml. The AUTH_SAML_* variables follow the AUTH_OIDC_* rule: Portal reads them only with --auth saml, and it rejects an --auth-saml-* flag on the command line without --auth saml.

Protect it with one-time sign-in links that Portal sends through your own SMTP account (see Email links):

# AUTH_SMTP_PASSWORD is set in this shell first, at a prompt
portal expose 3000 --auth email 
  --auth-smtp-addr smtp.gmail.com:587 
  --auth-smtp-username you@gmail.com 
  --auth-smtp-from you@gmail.com 
  --auth-email-list alice@example.com

--auth-email-list is required with --auth email. The AUTH_SMTP_* variables follow the AUTH_OIDC_* rule: Portal reads them only with --auth email, and it rejects an --auth-smtp-* flag on the command line without --auth email.

--auth-allow is the list for siwe and credential. --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, so existing configs keep working. Setting both is refused. email takes only --auth-email-list.

Portal protects the complete HTTP gateway, including routed, static, and x402 paths. It always strips inbound Portal identity headers. The auth gate cannot be combined with relay cache mode or raw TCP/UDP exposure.

Use a custom name and relay:

portal expose localhost:8080 
  --name myapp 
  --relays https://portal.example.com 
  --discovery=false

Run routed HTTP mode:

portal expose --name myapp 
  --http-route /api=http://127.0.0.1:3001 
  --http-route /=http://127.0.0.1:5173

Route matching is longest-prefix-first. /api matches /api/* and strips the /api prefix before proxying to the upstream.

Expose a Minecraft server:

portal expose localhost:25565 --name minecraft --tcp

Enable UDP alongside the default stream target:

portal expose localhost:8080 --udp --udp-addr localhost:19132 --name game

Ban relays on MITM probe detection:

portal expose 3000 --ban-mitm

Publish a paid HTTP route:

portal expose --name paid-app 
  --http-route "/paid=http://127.0.0.1:3001 GET:0.01" 
  --http-route /=http://127.0.0.1:5173 
  --x402-pay-to 0x...

The optional method list limits which methods require payment; without it, every method on that route prefix is paid.

The routed HTTP handler also serves /x402/client.js and /x402/prepare on the public tunnel origin. Frontends served by one of the routes can use the shared browser-only Sui wallet client for an in-page payment flow:

import { getSuiWallets, x402Fetch } from '/x402/client.js';

const [wallet] = getSuiWallets();
if (!wallet) {
  throw new Error('Install a Sui wallet');
}

const [account] = await wallet.accounts();
if (!account) {
  throw new Error('Connect a Sui account');
}

const response = await x402Fetch('/paid/photo', { method: 'GET' }, {
  wallet,
  account,
  onEvent: (event) => console.log(event.type, event.message),
});

x402Fetch() is a convenience wrapper: it asks /x402/prepare for the payment transaction, asks the wallet to sign it, then retries the protected request with an X-PAYMENT header. onEvent receives structured progress events; the older onStatus(message) callback is still accepted for simple UIs. Routed HTTP payments use Sui mainnet by default; pass --x402-testnet when exposing the tunnel and use network: 'sui:testnet' in wallet clients that need an explicit network. For mainnet, omit network or pass sui:mainnet.

Native clients should not load /x402/client.js. Call POST /x402/prepare with { "sender": "...", "method": "GET", "path": "/paid/photo" }, execute prepareTransaction.transaction first when present, sign paymentTransaction.transaction, and send the resulting x402 payload as the X-PAYMENT header on the protected request:

const payload = {
  x402Version: prepared.x402Version,
  payload: {
    signature,
    transaction: prepared.paymentTransaction.transaction,
  },
  accepted: prepared.paymentRequirements,
  resource: prepared.resource,
};
const header = base64(JSON.stringify(payload));

The frontend integration is optional. Requests without a valid X-PAYMENT header still receive x402 payment-required responses from the tunnel.

Serve A Static Site

portal expose --serve ./dist
# An HTML file serves its containing folder with that file as the SPA entry.
portal expose --serve ./site/index.html

Unknown paths fall back to the entry HTML file. Keep private files outside the served directory. Path traversal (..) is refused, and a symlink whose target is outside the folder answers 404; a symlink inside the folder is followed. Static serving is available in both expose and agent TOML; the agent format supports serve but not relay cache options (cache or cache_ttl).

To opt in to storage and TLS termination at one selected relay:

portal expose --serve ./dist --cache --cache-ttl 1h 
  --relays https://gosunuts.xyz --discovery=false

The selected relay must advertise cache support and admit the snapshot. Otherwise the live origin tunnel remains in use. A cached connection trusts the relay with the files and HTTP traffic, even if it falls back to the live origin. Only the granted friendly alias is cached; the canonical hostname continues to require a live origin. The requested TTL is an upper request subject to relay policy, not a hosting guarantee; cached files may be evicted or lost on relay restart. See cache configuration and the TLS boundary.

portal auth issue

Issue a host-scoped credential using an existing tunnel identity:

portal auth issue [flags] <host>
portal auth issue myapp.example.com --subject alice --expires 720h
FlagTypeDefaultDescription
--subjectstringrequiredSubject placed in the credential and optional upstream identity header
--expiresduration720hCredential lifetime
--identity-pathstringidentity.jsonExisting tunnel identity; no identity is created by this command
--identity-jsonstringIn-memory existing tunnel identity; IDENTITY_JSON environment variable; takes precedence over the path

The command prints a bearer credential and an HTTPS redeem URL. <host> is the published hostname, or an https:// URL of it; the default port :443 is ignored, and a relay on another port must include it (myapp.example.com:8443). Use it with a tunnel started via portal expose ... --auth credential. API clients can send the credential in X-Portal-Access-Credential; Portal validates and removes that header before forwarding the request upstream.

portal list

Print relay URLs resolved for the current invocation:

portal list [flags]
FlagTypeDefaultDescription
--relaysstringregistryAdditional relay URLs
--default-relaysbooltrueInclude public registry relays

portal list does not run the runtime relay discovery expansion loop. It only resolves the registry seed list plus explicit relay URLs.

portal agent

Run a durable local agent that owns multiple tunnels from one config file:

portal agent run
portal agent dashboard
portal agent stop
portal agent restart
CommandDescription
portal agent runInstall or update and start the managed agent service
portal agent run --config config.toml --foregroundRun the agent in the current terminal
portal agent dashboardOpen the local TUI for tunnels, relays, and settings
portal agent stopGracefully stop the agent and disable or stop the OS service
portal agent restartStop the current agent if present, install or update the service, and start it again

The local control API binds only to loopback and uses a token in the agent state directory. See Portal Agent for the workflow and Configuration Reference for the config.toml format.

Agent flags:

CommandFlagDefaultDescription
portal agent run--configplatform defaultAgent TOML config path
portal agent run--foregroundfalseRun in the current process without installing the OS service
portal agent run--servicefalseInternal service entrypoint used by the installed OS service
portal agent run--themeamberDashboard color theme with --foreground: amber or green (env: PORTAL_TUI_THEME)
portal agent dashboard--configplatform defaultConfig path used for display and state-dir discovery
portal agent dashboard--state-dirconfig/defaultAgent state directory to attach to
portal agent dashboard--themeamberColor theme: amber or green (env: PORTAL_TUI_THEME)
portal agent stop--configplatform defaultConfig path used to resolve state dir and service name
portal agent stop--state-dirconfig/defaultAgent state directory to stop
portal agent restart--configplatform defaultConfig path used to reinstall and restart the service

portal update

Update the CLI binary:

portal update

The updater resolves the latest GitHub release, compares it with the installed version, downloads the matching asset, verifies its SHA256 checksum, and replaces the current executable.

portal version

portal version

Prints the installed version string and exits.

Behavior Notes

  • portal expose and portal list check the latest published GitHub Release in the background. A main merge or branch artifact is not offered to installed clients until the release is created with matching binary and checksum assets.
  • portal expose loads or creates a signing identity at identity.json or --identity-path.
  • Multiple relay URLs are registered independently. A failed relay does not stop healthy relays from serving.
  • With --discovery=false, nothing replaces a failed relay, so portal expose logs each relay’s error and exits with a nonzero status once every relay has failed, for example when each relay rejects the registration. With discovery enabled, it keeps running while discovery selects other relays.
  • With discovery enabled, the tunnel consumes relay /discovery results and reconciles its relay pool.
  • MITM self-probing logs suspected termination by default; relay banning requires --ban-mitm.
  • When the local stream target is unreachable, the tunnel returns an HTTP 503 page to browser-style clients.
  • Routed HTTP mode is HTTP-only and runs inside the tunnel process.
  • Routed HTTP mode keeps the browser’s Host for every upstream and sends X-Forwarded-Proto: https; a local dev server that checks Host (such as Vite’s server.allowedHosts) must allow the public hostname.
  • --tcp requires relay TCP port transport, a valid MIN_PORT/MAX_PORT range, and TCP port transport enabled in the admin panel.
  • --udp requires relay UDP transport, a valid MIN_PORT/MAX_PORT range, UDP enabled in the admin panel, and the public PORTAL_URL port reachable over UDP for the QUIC backhaul.
  • Bare portal [flags] is not accepted; use portal expose explicitly.
  • Runtime APP_*, RELAYS, and DEFAULT_RELAYS environment variable fallbacks are not used.

Next Steps