Security & Self-Hosting

If you self-host AxonOS on a public server — or expose ports beyond localhost — you are responsible for hardening your deployment. This page summarizes the essentials.

The default password is for development only

The build-time default axonpassword must never reach a public deployment. Always build with --build-arg PASSWORD="$AXONOS_VNC_PASSWORD" using a strong secret.

Checklist

🔑Strong VNC password

Set a strong password at build/run time. It guards both the desktop and in-container sudo.

🚫Don't expose direct VNC

Avoid publishing port 5901 to the internet. Reach the desktop via noVNC (6080) behind TLS instead.

🔒Terminate TLS at a proxy

Put a reverse proxy in front that terminates TLS and applies rate limits, request-size limits, and IP allowlists where appropriate.

📡Lock down IPFS

Exposing the IPFS API (5001) publicly is risky — restrict it to trusted networks.

Port exposure

Port	Service	Recommendation
`6080`	noVNC	Expose behind a TLS reverse proxy
`8889`	Gate API	Expose behind the same proxy; required for billing/auth
`5901`	Direct VNC	Do not expose publicly
`5001`	IPFS API	Do not expose publicly; trusted networks only
`4001`, `8080`, `9090`	IPFS swarm / gateway / metrics	Optional; restrict as needed

Reverse proxy & TLS

When using a tunnel or reverse proxy, ensure it:

Terminates TLS for both noVNC and the gate API.
Applies rate limits and request-size limits to blunt abuse.
Uses IP allowlists for admin or non-public instances.

For non-standard hosting setups, configure the gate via environment variables — allowed origins and rate limits — so wallet verification keeps working while reducing cross-origin abuse. See Configuration.

Secrets hygiene

Keep .env out of version control.
Rotate AXGT_SESSION_LAUNCHER_TOKEN and WEBRTC_AGENT_INTERNAL_KEY away from their placeholder values before going live.
Use a revenue address you control for AXGT_REVENUE_WALLET; no revenue private key belongs in the gate configuration.
Use a dedicated low-balance hot key for X402_SETTLEMENT_PRIVATE_KEY; never reuse a revenue or treasury key. Keep CDP credentials, the admin secret, TURN credentials, database passwords, and WebRTC signing material out of logs and tenant environments.
Keep postgres and axonos-launcher on the control network only. Tenant containers should receive media tuning and short-lived capabilities, not database, payment, or launcher credentials.

Supply-chain integrity

For stronger build guarantees, pin and verify external installers where supported. For example, set OLLAMA_INSTALL_SHA256 so the build verifies the Ollama install script hash before running it.

The launcher mounts the Docker socket

In the Compose stack, axonos-launcher mounts /var/run/docker.sock to spawn session containers. Treat the launcher as privileged — keep its token secret and its network surface minimal.

Responsible disclosure

Security issues should be reported privately to the maintainers as described in the repository's SECURITY.md, rather than via public issues.