Installation

This page covers building and running AxonOS directly with Docker. If you'd rather use the guided tool, see The AxonOS Launcher; for the full multi-service stack, see Docker Compose.

1. Get the source

bash

git clone https://github.com/AXDT-INC/AxonOS.git
cd AxonOS
cp env.example .env

Edit .env and set, at minimum, AXONOS_VNC_PASSWORD. See Configuration for the full variable reference.

2. Build the image

bash

# Recommended: build with a custom password
docker build --build-arg PASSWORD="$AXONOS_VNC_PASSWORD" -t axonos .

# Or use the helper script
./scripts/build_axonos.sh "$AXONOS_VNC_PASSWORD"

# Or build with the default dev password (NOT for production)
docker build -t axonos .

Pin the NVIDIA userspace to your host driver

On GPU hosts, build with --build-arg NVIDIA_DRIVER_PKG_VERSION=$(nvidia-smi --query-gpu=driver_version --format=csv,noheader) to keep the in-container Xorg NVIDIA libraries in lockstep with the host driver and avoid GLX mismatch crashes.

3. Run the container

The recommended default exposes only the browser desktop on port 6080:

bash

docker run -d --gpus all --env-file .env -p 6080:6080 \
  --name axonos-lab axonos

To also publish direct VNC and IPFS ports (only if you explicitly need host access):

bash

docker run -d --gpus all --env-file .env -p 6080:6080 \
  -p 5901:5901 \
  -p 4001:4001 -p 4001:4001/udp -p 5001:5001 -p 8080:8080 -p 9090:9090 \
  --name axonos-lab axonos

Ports are about exposure, not features

Not publishing VNC/IPFS ports does not remove functionality inside the desktop — it only keeps those services off the host/internet by default.

4. Access the desktop

URL	Description
`http://localhost:6080/vnc.html`	Full Linux desktop in browser (use your VNC password)
`http://localhost:8080`	IPFS Gateway (if published)
`http://localhost:5001`	IPFS API (if published)
`http://localhost:5001/webui`	IPFS Web UI (if published)

Managing the container

bash

# Follow logs
docker logs -f axonos-lab

# Stop / start / remove
docker stop axonos-lab
docker start axonos-lab
docker rm -f axonos-lab

# Open a shell inside the running desktop
docker exec -it axonos-lab bash

Persisting your workspace

Mount a host directory onto the in-container home folder so your work survives container restarts:

bash

docker run -d --gpus all --env-file .env -p 6080:6080 \
  -v "$HOME/axonos-data:/home/aXonian" \
  --name axonos-lab axonos

Default user

The default desktop user is aXonian. The launcher can rewrite this when generating a custom Dockerfile.

Continue to Docker Compose to run the full gated platform.