Quick Start (Docker)
This guide self-hosts a single AxonOS desktop — from a fresh clone to a full Linux desktop running in your browser. For the fully orchestrated, wallet-gated stack (gateway + billing + Postgres), see Docker Compose.
You don't need to build anything to use the hosted platform — open app.axonos.io and follow Launch AxonOS. This page is for running it on your own machine.
You need Docker 20.10+ with BuildKit. For GPU acceleration you also need an NVIDIA GPU and the NVIDIA Container Toolkit. See System Requirements for the full list.
1. Configure your environment
AxonOS is configured through environment variables. Copy the example file and fill in the
placeholders — never commit your real .env.
cp env.example .env
At minimum, set a strong VNC password:
# .env
AXONOS_VNC_PASSWORD=choose-a-strong-password
2. Choose how to launch
⌨️CLI Launcher
The fastest path on headless GPU servers — list, build, and deploy with one tool.
Recommended for servers →🐳Manual Docker
Build and run the image directly with docker build / docker run.
🖱️GUI Launcher
A point-and-click customizer for selecting apps, models, and build options.
Desktop systems →Option A — CLI Launcher (recommended)
Clone the repository
git clone https://github.com/AXDT-INC/AxonOS.git && cd AxonOS
List available applications
axonos list shows every bundled tool and whether it's enabled.
Build the image
axonos build --password "$AXONOS_VNC_PASSWORD"
Deploy with GPU
axonos deploy --gpu builds the run command, starts the container, and opens your browser.
git clone https://github.com/AXDT-INC/AxonOS.git
cd AxonOS
axonos list
axonos build --password "$AXONOS_VNC_PASSWORD"
axonos deploy --gpu
See the full CLI Reference for every command and flag.
Option B — Manual Docker
git clone https://github.com/AXDT-INC/AxonOS.git
cd AxonOS
# Build with a custom password (recommended)
docker build --build-arg PASSWORD="$AXONOS_VNC_PASSWORD" -t axonos .
# Run — exposes the browser desktop on port 6080
docker run -d --gpus all --env-file .env -p 6080:6080 \
--name axonos-lab axonos
Drop the --gpus all flag to run on CPU. GPU-accelerated tools simply fall back to
software rendering.
Option C — GUI Launcher
On a machine with a display, launch the point-and-click customizer:
axonos --gui
Use it to select which applications to include, configure AI models, set credentials, and build & deploy with one click.
3. Open AxonOS
Once the container is running, open these in your browser:
| URL | What it is |
|---|---|
http://localhost:6080/vnc.html | Full Linux desktop (log in with your VNC password) |
http://localhost:8080 | IPFS Gateway (if IPFS ports are published) |
http://localhost:5001/webui | IPFS Web UI (optional) |
The default build password axonpassword is for development only. Always pass
--build-arg PASSWORD=… for any deployment reachable beyond localhost. See
Security & Self-Hosting.