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 / queue ─────► Session Manager (session_manager.py)
                                                    │
                                                    ▼
                                            Session Launcher (session_launcher.py)
                                                    │  CLI or HTTP API
                                                    ▼
                                            Host Docker Launcher
                                                    │  manage lifecycle
                                                    ▼
                                  AxonOS Desktop Containers (XFCE, Assistant, VNC)
                                                    │  VNC/WebRTC stream
                                                    └────────────► 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, assigns physical GPUs exclusively, queues fairly 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	noVNC + Websockify	Browser access over WebSockets (WebRTC is an optional path)
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 joins them to the axonos_stack network so the gate can reach their WebRTC agents.

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.