Deploying with Docker Compose

The repository ships a docker-compose.yml that brings up the complete single-instance public-beta stack: the gated axonos service, the HTTP axonos-launcher that spawns per-session desktops, a postgres ledger, coturn, and an optional-certificate files-tls edge service.

Two ways to run AxonOS

For a single personal desktop, the plain docker run in Installation is enough. Use Compose when you want the wallet-gated, multi-session platform with billing and GPU scheduling — the same shape that powers app.axonos.io.

TL;DR

bash

git clone https://github.com/AXDT-INC/AxonOS.git
cd AxonOS
cp env.example .env          # then edit secrets — see Configuration

docker volume create axonos_letsencrypt
docker compose build
docker compose up -d

# UI:        http://HOST:6080/vnc.html
# Gate API:  http://HOST:8889

What's in the stack

Service	Image / build	Role
`axonos`	`Dockerfile` → `axonos:public-beta`	Gate server + billing + session orchestration entrypoint
`axonos-launcher`	`docker/launcher/Dockerfile`	HTTP launcher that spawns per-session desktop containers
`postgres`	`postgres:15-alpine`	Challenges, auth tokens, sessions, and the deposit/credit ledger
`coturn`	`coturn/coturn:4.6.2-alpine`	TURN/STUN relay for WebRTC streaming behind firewalls
`files-tls`	`nginx:1.27-alpine`	Shares public TCP 443 between direct HTTPS files and TURN-over-TCP

The control plane (postgres and axonos-launcher) uses axonos_control; it is not attached to the tenant-facing stack network. The central axonos gate bridges axonos_control and axonos_stack. With isolation enabled (the default), each session gets a launcher-managed bridge shared only with the gate. coturn and files-tls use axonos_stack.

Why a separate launcher?

The base axonos service runs gate-only (no Xorg) so a GPU stays free for the desktop sessions. The launcher mounts the host Docker socket and starts axgt-session-* desktop containers on demand, assigning GPUs with --gpus device=N. See Architecture.

Canonical topology

Use the repository Compose file

Deploy with the maintained docker-compose.yml. It is the source of truth for health checks, dependencies, GPU utility access, isolated session networking, media-variable passthrough, storage mounts, port ranges, and the external certificate volume. A shortened copy can weaken the control-plane boundary.

Key environment variables

These are read from your .env. The compose file auto-derives AXGT_CHALLENGE_DB_URL for you, so you usually only set credentials and chain config.

Variable	Default	Purpose
`AXONOS_VNC_PASSWORD`	(required)	Build arg `PASSWORD` — VNC + in-container sudo
`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	`axonos_gate` / `axonos_gate_secret` / `axonos_gate`	Bundled Postgres credentials
`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
`NVIDIA_DRIVER_PKG_VERSION`	(empty)	Pin in-container NVIDIA userspace to the host driver
`AXGT_HOST_SESSION_NETWORK_ISOLATION`	`true`	Give each tenant a gate-only session bridge
`AXGT_PERSISTENT_STORAGE_ENABLED`	`true`	Mount wallet-scoped home volumes
`FILES_TLS_SERVER_NAME`	deployment-specific	Certificate name used by `files-tls`

axonos_letsencrypt is an external volume and must exist before Compose starts. This makes a missing certificate volume fail loudly rather than silently creating an empty one. The launcher is privileged and mounts the Docker socket and /dev; do not publish it or Postgres. Replace the launcher token and database password defaults before production use.

Creating the volume only provides the mount expected by Compose; it does not provision a valid certificate. Follow the repository's certificate-provisioning procedure before enabling the public TLS file plane. This is an operator step and is not part of using the hosted service.

For billing/auth (AXGT_RPC_URL, AXGT_CONTRACT_ADDRESS, AXGT_REVENUE_WALLET, …) see Configuration and Tokenomics.

Lifecycle

bash

docker compose build            # build axonos + launcher images
docker compose up -d            # start the stack
docker compose ps               # service status + health
docker compose logs -f axonos   # follow gate logs
docker compose down             # stop and remove containers
docker compose down -v          # also drop the postgres volume (wipes the ledger!)

down -v destroys the ledger

docker compose down -v removes axonos_postgres_data — all credit balances, sessions, and auth tokens are lost. Omit -v for normal restarts.

GPU notes

The base axonos service intentionally reserves no GPUs — the launcher assigns specific devices to each axgt-session-* desktop with --gpus device=N. If nvidia-smi is available on the host, the base container auto-detects the GPU pool; otherwise the gate asks the launcher to enumerate GPUs. Ensure the NVIDIA Container Toolkit is installed on the host (see System Requirements).

Next: understand what the stack is doing under the hood in Architecture.