Quickstart

1. Start a persistent Linux instance

cd /srv/workspaces
aircode start

First run output:

Generated password: k6uu3U6UG8AXgTnvNgNj
Started workspaces (1a2b3c4d5e6f) on http://127.0.0.1:7860.
Service: aircode@workspaces-1a2b3c4d5e6f.service — restart after crashes and automatic boot: enabled.

AirCode Ø picks a free port automatically (7860 upward), generates an access password, and saves a private instance config outside the projects directory. If Tailscale is present, it binds your tailnet IP so your phone can reach it; otherwise it binds localhost only.

aircode start is persistent by default on Linux: systemd restarts the server after a crash and starts it again at boot. For a foreground process tied to the current terminal, use aircode serve instead.

2. Open the cockpit

Open the printed URL on any device that can reach the machine and log in with the password. For an installable phone or tablet client, first give the instance a stable HTTPS address through Remote Access, then choose one of these paths:

• On Web app setup, enter only that HTTPS instance address and select Open install page. The same setup remains available on Download. The address is validated in your browser and is never sent to or stored by the marketing website.
• On the instance itself, sign in and choose Install web app from More or Settings → Web app.
• In Chromium, accept the browser-owned install prompt. On iPhone or iPad, follow the in-product guide to choose Share → Add to Home Screen, keep Open as Web App enabled when shown, and launch the new Home Screen icon.

The web app is always available as the store-free client; it does not depend on Google Play, the App Store, TestFlight, or the downloadable release manifest. Plain HTTP LAN addresses can still open in a browser where allowed, but mobile installation, service workers and Web Push require HTTPS.

3. Launch your first session

1. Pick a project directory.
2. Pick the execution environment:
   • Local runs through host tmux or Windows ConPTY.
   • Docker sandbox runs one supported direct session in a worker while mounting the selected project.
3. Pick an engine (Claude Code, Codex, Antigravity CLI, Grok Build, Kimi Code) and a permission mode.
4. Launch. The agent keeps running on the AirCode Ø machine — close the tab, take the train, come back: it’s still working. Notifications ping you when the agent needs input or finishes.

The Web, Desktop and native mobile launchers expose the same environment choice. Docker is currently a Codex source preview; see Docker sandbox before enabling bypass permissions.

4. Operate it like a container

aircode ps                     # running instances
aircode ps -a                  # include stopped instances
aircode inspect                # current directory's instance
aircode logs --follow
aircode restart
aircode stop                   # stop now and disable startup at boot

Run lifecycle commands from the instance root, or pass its name, full ID, short ID, or root path. Stopping or updating the server never kills running tmux sessions. A whole-machine reboot necessarily stops operating-system processes, but durable session history remains available for recovery.

5. Choose ports, passwords, and multiple roots

Every value can be supplied on the launch command:

aircode start --projects-root /srv/client-a --port 7860 --generate-password
aircode start --projects-root /srv/client-b --port 7861 --password-file ~/.secrets/client-b
aircode start --projects-root /srv/demo --host 127.0.0.1 --port 7862 --no-password --relay private

Password files must be private (chmod 600). --password-stdin is available for provisioning systems. --password <value> works too, but exposes the secret to shell history and potentially process inspection. Disabling auth must be explicit with --no-password.

One canonical path normally maps to one instance. Add names when the same path needs several independent ports or policies:

aircode start --projects-root /srv/client-a --name internal --port 7860 --generate-password
aircode start --projects-root /srv/client-a --name demo --host 127.0.0.1 --port 7861 --no-password --relay private

6. Sign in before using managed Relay

aircode login
aircode whoami
aircode start --relay managed

The account authorization is shared by this Unix user’s instances. Ports, passwords, tunnel identities, and Relay enabled state remain isolated per instance. Managed Relay refuses an instance without a password. Use aircode logout to remove the machine credential, --relay private for a VPN without a public tunnel, or --relay off to disable a tunnel without forgetting its selected transport.

7. Install the agent CLIs

Packaged AirCode Ø releases already carry their pinned CLIs. For a source checkout, install and authenticate the CLIs under the same Unix user. The current distribution targets are:

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.211
claude

curl -fsSL https://chatgpt.com/codex/install.sh | bash -s -- --release 0.153.4
codex login

curl -fsSL https://x.ai/cli/install.sh | bash -s 0.2.118
grok login

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash -s -- --version 0.32.0
kimi login

An older or unreadable version is blocked. A newer release can launch and keeps screen-verified controls enabled unless a known incompatibility is recorded. aircode doctor commands report what is available.

Antigravity CLI uses Google’s official installer:

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy

The native engines keep their vendor authentication model:

Google retired Gemini CLI for individual accounts on June 18, 2026 and directs that plan at the Antigravity suite. AirCode Ø follows that move: Antigravity CLI is the Google engine, and Gemini CLI can no longer be selected. Sessions created with it before the change stay readable in History. See the official transition notice.

An Antigravity subscription is not required to connect: a Google account gets the baseline plan, while Pro and Ultra increase model access and limits. AirCode Ø uses the account-specific catalogue returned by agy models. See Google’s Antigravity plans and model catalogue.

For bundled API provider profiles, open AI Usage, choose the provider, and click Connect. AirCode Ø validates the submitted key, stores it locally in ~/.config/aircode/providers.env with private permissions, and activates it for new sessions immediately. The same screen can replace or disconnect keys. Keys supplied through the server environment remain supported and are shown as externally managed instead of being editable in the UI.

DeepSeek, Z.AI and MiniMax are selectable as Claude Code provider profiles; Meta Muse Spark is selectable through Kimi Code. DeepSeek uses DEEPSEEK_API_KEY; Z.AI uses a GLM Coding Plan key in ZAI_API_KEY; MiniMax accepts either a Token Plan Subscription Key or a pay-as-you-go key in MINIMAX_API_KEY; Meta uses META_MODEL_API_KEY and also recognizes Meta’s official MODEL_API_KEY alias. AirCode Ø injects each credential only into a session using that provider and never returns it through the API.

Grok uses a stored browser session before XAI_API_KEY; run grok logout when you explicitly want the API-key path.