Troubleshooting

First reflexes

aircode status              # service? server? which port, which version
aircode logs --follow       # live logs (systemd installs)
aircode doctor packaging    # install integrity: checksums, runtime, symlink
aircode doctor browser      # agent browser stack
aircode doctor tokens       # token-optimization stack

Common cases

I lost the password. aircode password reset, then restart the server.

The URL doesn’t load from my phone. The server binds Tailscale-or-localhost by default. Check aircode status for the bound address; make sure the phone is on the same tailnet/VPN. See Remote access.

Port already in use. AirCode Ø auto-scans from 7860 unless you pinned a port explicitly — a pinned busy port is an error by design. Unpin it or free it.

tmux or git missing. Install them (sudo apt-get install -y git tmux) and re-run. The installer and doctor list exactly what’s missing.

An engine isn’t detected. The CLIs must be installed and authenticated for the same user that runs AirCode Ø. Try running claude (or codex, …) in a shell as that user first.

Docker sandbox is unavailable. The launcher shows the authoritative reason. Start Docker, then run npm run docker:runtime:build for the current source preview or pull the configured public image once it exists. Confirm with npm run docker:runtime:check.

DOCKER_ENGINE_UNAVAILABLE. The image is valid, but that engine is not certified in its io.aircode.engines label. Choose Codex in the current preview or switch the session to Local.

DOCKER_CONTROL_UNAVAILABLE. The worker callback bridge could not bind its stable port. Free AIRCODE_DOCKER_CONTROL_PORT or configure another fixed port, then restart AirCode before launching a new worker.

My VPN does not carry agent traffic. Docker egress uses bridge/NAT traffic, which some split-tunnel VPNs exclude. Add the Docker subnet to the VPN/firewall policy. The managed AirCode tunnel is inbound control-plane access, not an outbound worker VPN.

A dev server started in Docker is not reachable. Worker ports are not published in the current preview. Authenticated forwarding through AirCode and the Hetzner route is a planned networking increment.

Update says my version is too old. Very old installs must reinstall via the one-liner instead of updating in place — the message says so explicitly.

The install looks corrupted. aircode doctor packaging pinpoints altered files; re-run the installer to repair (curl -fsSL …/install.sh | bash). Your config, sessions and data are untouched — they live outside the version directory.

Restricted mode (license). aircode license status explains why. Activation takes effect immediately — no restart needed.

Still stuck?

Grab aircode status, aircode doctor packaging --json and the last 100 log lines, and write to support@aircode.example. No logs contain your code or prompts.