Configuration

AxonOS is configured almost entirely through environment variables. Copy env.example to .env for local and Compose deployments, then fill in the placeholders.

bash

cp env.example .env

Never commit secrets

.env contains passwords, RPC URLs, and wallet addresses. Keep it out of version control.

How configuration layers work

Layer	Mechanism	Notes
Operator `.env`	`env_file: .env` in `docker-compose.yml`	Primary runtime config for gate, launcher, Postgres
Compose overrides	`environment:` blocks	Injects DB URL, launcher URL, gate bind, WebRTC defaults
Build args	`docker build --build-arg …` / compose `build.args`	Image credentials and NVIDIA pinning
Runtime injection	Session launcher `docker run -e …`	Per-session vars (session id, GPU assignment)
Image defaults	`ENV` in `Dockerfile`, supervisord	NVIDIA, OpenMPI, VirtualGL — rarely overridden

Build-time vs run-time: AXONOS_VNC_PASSWORD / PASSWORD and NVIDIA_DRIVER_PKG_VERSION affect the image at build. Most AXGT_* and WEBRTC_* vars are read at process start.

Boolean convention: truthy values are 1, true, yes, on (case-insensitive); falsy is 0, false, no, off.

Build & image

Variable	When	Purpose
`AXONOS_VNC_PASSWORD` / `PASSWORD`	build	Sets the `aXonian` user password, VNC passwd, and sudo access. Default `axonpassword` is dev-only.
`NVIDIA_DRIVER_PKG_VERSION`	build	Pins in-container NVIDIA userspace to the host `nvidia-smi` driver to avoid GLX crashes.
`NVIDIA_DRIVER_VERSION`	build (ARG, default `535`)	Major NVIDIA driver branch for package names.
`OLLAMA_INSTALL_SHA256`	build (optional)	Verifies the Ollama install script hash (supply-chain hardening).
`USER`	build (ENV, default `aXonian`)	Primary desktop user inside the container.

Required for the production gate + billing

Variable	Purpose
`AXGT_CONTRACT_ADDRESS`	AXGT ERC-20 contract for balance checks / legacy AXGT deposits
`AXGT_CHAIN_ID`	Chain ID exposed to UI and wallet flows (`1` mainnet, `11155111` Sepolia)
`AXGT_RPC_URL`	JSON-RPC endpoint for deposits, receipts, and `balanceOf`
`AXGT_REVENUE_WALLET`	Recipient address for ETH / AXGT deposits
`AXGT_CHALLENGE_DB_URL`	Postgres URL for challenges, auth tokens, sessions, ledger

Compose auto-sets the DB URL

With the repo docker-compose.yml, AXGT_CHALLENGE_DB_URL is auto-set on the axonos and axonos-launcher services. Omit it from .env unless you use an external database.

Compose & deploy (common)

Variable	Default	Purpose
`POSTGRES_USER`	`axonos_gate`	Bundled Postgres user
`POSTGRES_PASSWORD`	`axonos_gate_secret`	Bundled Postgres password
`POSTGRES_DB`	`axonos_gate`	Bundled Postgres database name
`AXONOS_PUBLISH_NOVNC`	`6080`	Host port → container noVNC
`AXONOS_PUBLISH_GATE`	`8889`	Host port → container gate API
`AXGT_SESSION_LAUNCHER_TOKEN`	`change-me-launcher-token`	Shared secret between gate and launcher

Payment rails

The deposit/credit model is configured through AXGT_*, ETH_*, and USDC_* variables. A few of the most common:

Variable	Default	Purpose
`AXGT_ENABLE_ETH_DEPOSITS`	`true`	Enable native ETH deposit verification + UI
`ETH_MIN_DEPOSIT`	`0.0005`	Minimum ETH per deposit (before holder discount)
`ETH_CREDIT_PER_ETH_MINUTES`	`120000`	Minutes credited per 1 ETH
`AXGT_ENABLE_AXGT_DEPOSITS`	`false`	Opt-in direct AXGT payment rail
`AXGT_TOKEN_DECIMALS`	`18`	ERC-20 decimals for the "send min AXGT" UI

The full pricing model — discount tiers, USDC, and the agent-native x402 rail — is explained in Tokenomics & AXGT.

WebRTC (browser-native streaming)

Optional low-latency streaming uses a capture agent plus STUN/TURN. Key toggles:

Variable	Default	Purpose
`WEBRTC_ENABLED`	`false`	Enable the WebRTC stream path
`WEBRTC_FALLBACK_ENABLED`	`true`	Fall back to noVNC if WebRTC fails
`WEBRTC_AGENT_INTERNAL_KEY`	(none)	Shared secret between gate and capture agent
`WEBRTC_STUN_URLS` / `WEBRTC_TURN_URLS`	(none)	ICE servers (the compose `coturn` service provides TURN)

Full reference

This page is a curated overview. The exhaustive variable-by-variable reference lives in the repo at docs/ENVIRONMENT_VARIABLES.md, kept in sync with env.example.