Troubleshooting

First reflexes

aircode ps -a               # every path-scoped instance and its boot state
aircode inspect [instance]  # root, port, auth, Relay, service and state paths
aircode logs [instance] --follow
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. Run aircode password reset [instance]. A persistent Linux instance restarts automatically with the new password.

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.

The instance restarts after a crash but not until I log in after reboot. aircode inspect reports Boot: after-login when the unit is enabled but systemd linger is unavailable. Run the exact command printed by aircode start, normally sudo loginctl enable-linger $USER, then confirm that loginctl show-user $USER --property=Linger reports Linger=yes.

The service is in a restart loop. Check aircode logs <instance> first. A port pinned in the instance config may now be occupied, a projects root may no longer exist, or a required system dependency may be unavailable. Fix the reported cause and run aircode restart <instance>.

A root selector is ambiguous. Several named instances use the same path. Run aircode ps -a and target the unique name or short ID.

Managed Relay says login is required. Authorize the Unix user once with aircode login, verify with aircode whoami, and retry aircode start <instance> --relay managed. Managed Relay also requires a non-empty instance password.

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 -s -- --channel beta). 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 ps -a --json, aircode inspect <instance> --json, aircode doctor packaging --json, and the last 100 log lines, then use the support channel supplied with your beta invitation. Review the output before sharing it; diagnostic logs are designed not to contain code or prompts.