Architecture

AxonOS is more than a desktop image. The hosted platform is a small distributed system: a browser client talks to a gate server that handles Web3 auth and billing, which drives a session manager and launcher that schedule GPU desktop containers on demand.

High-level system

The client communicates with the gated server over standard WebSockets and HTTPS. The gate verifies Web3 signatures, indexes on-chain deposit logs via an Ethereum RPC node, persists credit balances in PostgreSQL, and schedules session containers dynamically through the local Docker CLI or a remote HTTP launcher service.

text

Web Browser (noVNC / WebRTC UI)
        │  port 6080 — WebSockets & HTTP
        ▼
Gate Server (websockify_gate.py / gate_server.py)
        ├── Auth, deposit & audit ledgers ──► PostgreSQL (axgt_deposits, axgt_ledger)
        ├── JSON-RPC balanceOf & tx checks ─► Ethereum RPC Node (mainnet)
        └── Claim / heartbeat / status ────► Session Manager (session_manager.py)
                                                    │
                                                    ▼
                                            Session Launcher (session_launcher.py)
                                                    │  CLI or HTTP API
                                                    ▼
                                            Privileged Host Docker Launcher
                                                    │  manage lifecycle
                                                    ▼
                                  Isolated AxonOS Session Containers
                                                    │  WebRTC (or legacy VNC path)
                                                    └────────────► back to browser

The components

🛡️Gate Server

Verifies EIP-191 wallet signatures, computes discount quotes, confirms deposits on-chain, and gates desktop access on remaining credit minutes.

🧮Session Manager

Claims GPU resource profiles with atomic reservations, assigns physical GPUs exclusively, returns capacity status under contention, and bills credits on each heartbeat.

🚀Session Launcher

Spawns and stops desktop containers — via local Docker CLI or a remote HTTP launcher — assigning GPUs with --gpus device=N.

🗄️Postgres Ledger

Stores challenges, auth tokens, sessions, and the deposit/credit ledger that every billing decision reads from.

The desktop image

Inside each desktop container, a process supervisor keeps the streaming and research services alive:

Layer	Component	Role
Desktop	XFCE4	Lightweight desktop environment with a customized layout
Display	TigerVNC	VNC server exposing the XFCE desktop
Transport	WebRTC + noVNC UI	Browser-native media; classic VNC fallback is for compatible legacy/single-container mode
GPU	OpenCL / CUDA / VirtualGL	Accelerated computing and GL forwarding
Process mgmt	Supervisor	Keeps `vncserver`, noVNC, JupyterLab, and the assistant running

Two operating modes

🖥️Single desktop

A plain docker run starts one self-contained desktop on port 6080. Great for local, offline, or classroom use. See Installation.

🌐Gated multi-session platform

Docker Compose runs the gate + launcher + Postgres + TURN. The gate spawns one axgt-session-* desktop per paying user, scheduled across the GPU pool. See Docker Compose.

Gate-only base container

In the multi-session stack the base axonos service runs gate-only (no Xorg) so GPU :0 stays free for session desktops. The launcher creates the actual desktops and gives each tenant an isolated bridge shared only with the central gate. Database, payment, launcher, and signing credentials remain in the control plane.

Request lifecycle

The end-to-end flow — from wallet connection through deposit verification, GPU claim, and the billing heartbeat — is documented step-by-step with sequence diagrams in User Flow & Gateway.