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 `580`)	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 and optional 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
`AXGT_ENABLE_USDC_DEPOSITS`	`true`	Enable the configured USDC transaction-hash rail and UI
`USDC_CHAIN_ID` / `USDC_NETWORK`	`8453` / `base`	USDC network; its RPC and contract must also be configured

AXGT_DYNAMIC_PRICING defaults to false for self-hosting. The hosted deployment explicitly enables it and direct AXGT deposits. Dynamic pricing needs Postgres for its trusted-price cache. Compose injects .env values when it creates a container, so recreate the affected service after changing them; a plain docker restart axonos does not reload Compose-managed environment values.

bash

docker compose up -d --no-deps --force-recreate axonos

Environment-only changes do not require an image rebuild. If application code or the image also changed, build first and then recreate the service.

Variable	Default	Purpose
`AXGT_DYNAMIC_PRICING`	`false`	Enable USD-equivalent server-side ETH/AXGT pricing
`PRICE_POLL_INTERVAL_SECONDS`	`300`	Lazy refresh cadence in seconds
`AXGT_TWAP_WINDOW_SECONDS`	`1800`	Uniswap v3 TWAP window (minimum 60 seconds)
`AXGT_MAX_PRICE_DEVIATION_PERCENT`	`25`	Threshold requiring independent CoinGecko agreement
`PRICE_MAX_STALE_SECONDS`	`86400`	Maximum trusted-cache age before fixed-rate fallback
`ETHEREUM_RPC_URL`	`https://ethereum-rpc.publicnode.com`	Preferred Ethereum RPC for Uniswap and Chainlink reads
`AXGT_UNISWAP_V3_POOL`	`0xf9c56A9CcC1398Bed3C519ef2F0B42CE52AaA440`	AXGT/WETH Uniswap v3 pool
`AXGT_COINGECKO_ID`	`axondao-governance-token-2`	CoinGecko confirmation/fallback identifier
`AXGT_USD_PER_HOUR`	`1.0`	Operator USD price for one hour at the 1-GPU rate
`AXGT_USD_BONUS_PERCENT`	`25`	Flat bonus for direct AXGT payments only

ETHEREUM_RPC_URL is preferred by the oracle. If unset, AXGT_RPC_URL is accepted as the Ethereum RPC fallback, followed by the public default. Treat credential-bearing RPC URLs as sensitive. The server rejects stale Chainlink ETH/USD data, guards spot quotes and large TWAP movements with CoinGecko, and never trusts a browser-reported price.

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)

Tenant sessions receive media tuning and a short-lived signed capability, not central database, payment, launcher, or fleet-signing credentials. Keep WEBRTC_AGENT_INTERNAL_KEY, TURN credentials, and launcher tokens secret. Microphone forwarding is separately opt-in with WEBRTC_MIC_ENABLED.

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.