This reference is derived from environment reads in the production Go source and its opt-in live tests. Empty values normally behave like unset values. Variables marked "conditional" are required only for the feature described.
| Variable | Role | Required | Default | Purpose |
|---|---|---|---|---|
WANCTL_ROLE |
container | No | relay |
Docker image command: relay, portal, or mcp. |
DATABASE_URL |
relay | Conditional | none | PostgreSQL DSN. Required for the portal-backed multi-user deployment; otherwise relay needs WANCTL_TOKENS or WANCTL_UPSTREAM_RELAY. |
WANCTL_AUTO_MIGRATE |
relay | No | enabled | Set to 0 to skip embedded database migrations. |
WANCTL_ADMIN_SECRET |
relay, portal, admin CLI | Conditional | none | Shared secret for /admin/*; relay startup requires at least 32 bytes when set. Required for a functional portal, upstream token resolution, admin CLI, and server-log access. |
WANCTL_TOKENS |
relay | Conditional | none | Static token:namespace pairs separated by commas; fallback for a relay without Postgres. |
WANCTL_UPSTREAM_RELAY |
relay | Conditional | none | Upstream relay URL used to resolve tokens when this relay has no database. Requires WANCTL_ADMIN_SECRET. |
WANCTL_PORTAL_NS |
relay | No | none | Namespace allowed to open privileged portal console sessions. Conventionally portal. |
WANCTL_DIST_DIR |
relay | No | /dist |
Directory containing signed release artifacts and installers. |
WANCTL_PUBLIC_ORIGIN |
relay | Conditional | none | Canonical relay origin substituted into /skills and into the installers served from /install.sh and /install.ps1, so a script fetched from this relay installs from this relay. Never derived from request Host: /skills returns 503 when unset, and the installers are served with their built-in base untouched. |
WANCTL_MCP_SEED |
relay, MCP | Conditional | none | Hex seed enabling /wanctl-mcp on relay; required and at least 32 decoded bytes for standalone mcp --http. |
WANCTL_MCP_LOCAL_ROOT |
MCP stdio | No | process working directory | Only local tree wanctl_push and wanctl_pull may access. The wanctl config directory is always excluded. |
WANCTL_MCP_ALLOWED_ORIGINS |
MCP HTTP | No | none | Comma-separated browser Origin allowlist. Requests with an Origin are denied unless listed; programmatic clients normally send none. |
WANCTL_MCP_ALLOW_UNSAFE_TRUST_SERVER |
MCP | No | 0 |
Set to 1 only to restore model-callable device TOFU pinning. Default is fail-closed because the model cannot distinguish an independently verified fingerprint from one supplied by a hostile relay. |
RELAY_ADMIN_URL |
portal | Yes | none | Internal relay base URL used for the portal's admin proxy, such as http://relay:8080. |
WANCTL_GITHUB_CLIENT_ID |
portal | Conditional | none | Enables GitHub OAuth login. Mutually exclusive with PORTAL_USER_HEADER. |
WANCTL_GITHUB_CLIENT_SECRET |
portal | Conditional | none | OAuth App client secret; required when the client ID is set. |
WANCTL_SESSION_SECRET |
portal | Conditional | none | HMAC key for OAuth state and session cookies; at least 32 bytes when OAuth is enabled. |
WANCTL_GITHUB_PROXY |
portal | No | none | HTTP(S) or SOCKS5 proxy for GitHub token/user requests only. Relay and other outbound traffic are unaffected. |
WANCTL_GITHUB_AUTH_BASE |
portal | No | https://github.com |
OAuth authorization/token base URL; useful for GitHub Enterprise. |
WANCTL_GITHUB_API_BASE |
portal | No | https://api.github.com |
GitHub user API base URL; useful for GitHub Enterprise. |
PORTAL_USER_HEADER |
portal | Conditional | X-Auth-Request-Email |
Trusted reverse-proxy identity header for header-auth mode. The proxy must strip client-supplied copies. Mutually exclusive with GitHub OAuth. |
PORTAL_PUBLIC_ORIGIN |
portal | No | derived from request | External portal origin used for OAuth redirects and secure cookies. Set it when TLS terminates at a proxy. |
PORTAL_DEBUG_WHOAMI |
portal | No | 0 |
Set to 1 to enable the diagnostic /whoami endpoint. Do not enable routinely. |
WANCTL_RELAY |
portal | Conditional | persisted config, then build-time default | Public relay URL used by the portal console and /skills redirect. Also used by clients and agents, who can persist it with wanctl config set relay=…. |
WANCTL_PORTAL_TOKEN |
portal | Conditional | none | Token in WANCTL_PORTAL_NS; required only for the live device console. |
WANCTL_TRANSPORT |
portal, agent, controller, MCP | No | http |
Carrier: proxy-agnostic http long-poll or ws. |
WANCTL_CONFIG_DIR |
all stateful roles | No | OS user config directory | Directory for identity, trust, token, label, logs, and process state. The container image sets /data. |
WANCTL_LARK_APP_ID |
portal | No | none | Legacy optional Lark approval integration; effective only when the matching secret is also set. |
WANCTL_LARK_APP_SECRET |
portal | No | none | Secret paired with WANCTL_LARK_APP_ID. |
| Variable | Role | Required | Default | Purpose |
|---|---|---|---|---|
WANCTL_PORTAL |
agent, controller | Conditional | persisted config, then build-time default | Portal URL used for login/enrollment and pairing links. Persist with wanctl config set portal=…. |
WANCTL_RELEASE_BASE |
agent, controller, installers | No | wanctl config set release_base=…, then the build-time default |
Base URL where signed release artifacts live flat (official builds bake the project's GitHub releases). wanctl update and the installers pull from it; empty falls back to the relay's /dl mirror. Persist it with wanctl config set release_base=https://relay.example.com/dl when the baked-in release page is unreachable from where the binary runs. |
WANCTL_AUTO_UPDATE |
agent | No | on |
Set to off to stop a running agent from replacing its own binary with a newer signed release. Read at every check, so it takes effect without a restart; persist it with wanctl config set auto_update=off. Development builds, the copy inside the Android APK, and a binary in a directory the agent cannot write are never replaced regardless. |
WANCTL_DIST_BASE |
installers | No | none | Installer-only override of the artifact source; wins over WANCTL_RELAY and the baked release base. |
WANCTL_TOKEN |
agent, controller, MCP | Conditional | saved token or none | Namespace bearer token. Overrides the token stored in the config directory. |
WANCTL_NO_PROMPT |
agent, controller | No | unset | Set to 1 to refuse every interactive question, including the first-run "which relay" one. The command prints the wanctl config set instruction and exits instead of asking. |
WANCTL_LABEL |
controller, MCP | No | saved label or generated MCP label | Human-readable controller identity shown during pairing. |
WANCTL_PORTAL_FPS |
agent | No | none | Comma-separated portal administrator fingerprints to seed. |
WANCTL_PORTAL_FP |
agent | No | none | Deprecated single-fingerprint alias, used only when WANCTL_PORTAL_FPS is unset. |
| Variable | Role | Required | Default | Purpose |
|---|---|---|---|---|
WANCTL_DNS |
Android agent/controller | No | system/Termux resolver, then built-in public resolvers | Comma-separated DNS server addresses; bare addresses use port 53. |
WANCTL_ELEVATION |
Android agent | No | disabled | Truthy value (1, true, yes, or on) enables Android su/ADB elevation channels. |
WANCTL_ADB_PORT |
Android agent | No | discovered port, then 5555 |
Comma-separated local adbd ports to try before other sources. |
WANCTL_DEVICE_NAME |
Android agent | No | wanctl-agent for ADB identity |
Name embedded in the local ADB key label. The Android app normally injects it. |
WANCTL_DEVICE_STATE_FILE |
Android agent | No | none | JSON state file written by the Android app for battery data and adbd discovery; normally injected by the app. |
| Variable | Role | Required | Default | Purpose |
|---|---|---|---|---|
WANCTL_RELEASE_SIGNING_KEY |
release manifest tool | Conditional | none | Base64 Ed25519 seed or private key; required to sign a release. |
WANCTL_RELEASE_RSA_KEY |
release manifest tool | Conditional | none | Base64 PKCS#8 or PKCS#1 RSA private key (at least 2048 bits) used for installer signatures. |
| Variable | Role | Required | Default | Purpose |
|---|---|---|---|---|
WANCTL_VERSION |
Docker build / compose | No | dev |
Version stamped into a self-hosted relay or portal image. Set it to the checked-out tag or git describe --always. |
WANCTL_RELEASE_PUBLIC_KEYS |
Docker build / compose | No | none | Comma-separated Ed25519 public keys baked into a self-hosted image so relay /dl can verify signed releases. |
WANCTL_DEFAULT_PORTAL |
Android build | No | none | Portal origin baked into an APK; an empty value leaves the runtime login dialog responsible for collecting it. |
WANCTL_BIN |
installers | No | platform-dependent | Destination path for the installed wanctl executable. |
These variables are not runtime service configuration. They keep tests that contact real external systems disabled unless an operator supplies all required values explicitly.
| Variable | Role | Required | Default | Purpose |
|---|---|---|---|---|
WANCTL_LIVE_RELAY |
client live test | Conditional | none | Relay URL for the remote-console end-to-end test. |
WANCTL_LIVE_DEVTOK |
client live test | Conditional | none | Token for the test device namespace. |
WANCTL_LIVE_PORTALTOK |
client live test | Conditional | none | Privileged portal namespace token. |
WANCTL_LIVE_TARGET |
client live test | No | alice/macbox |
Fully qualified target used by the live test. |
WANCTL_LARK_TEST_EMAIL |
Lark live test | Conditional | none | Recipient of the real approval-card probe. |
WANCTL_LARK_KEEP_CARD |
Lark live test | No | 0 |
Set to 1 to leave the probe card actionable instead of resolving it immediately. |
WANCTL_LARK_LIVE_SECONDS |
Lark live test | Conditional | none | Positive number of seconds to keep the real callback consumer connected. |
Standard process variables such as EDITOR, PREFIX, and TMPDIR are outside
the wanctl-specific API.