Configuration

For a managed instance, precedence is environment variables → instance config → global user config → defaults. aircode start options are persisted into the instance config before the service starts. Foreground aircode serve options override the environment for that process only.

The global file is ~/.config/aircode/config.json. Managed instance files live at ~/.config/aircode/instances/<id>.json; they are not placed in project directories. Secret-bearing files use mode 0600. The native Windows foreground options are listed in the Windows CLI reference.

Per-instance launch configuration

aircode start --projects-root /srv/workspaces --host 127.0.0.1 --port 7860 \
  --password-file ~/.config/aircode/workspaces-password

Dedicated flags cover root, name, host, port, public URL, every password input mode, and Relay. Any additional schema-backed value can be persisted with a repeatable --set key=value; values use JSON when valid:

aircode start --set maxSessions=64
aircode start --set workflows.maxConcurrent=2
aircode start --set 'browserAllowedHosts=["docs.example.com","*.internal.test"]'

Use --json for unattended provisioning. Its output never reveals an existing password; it includes a password only when this invocation generated it.

Common settings

Env	config.json	Default	Purpose
`AIRCODE_HOST`	`host`	Tailscale IP, else `127.0.0.1`	Bind address (never `0.0.0.0` by default)
`AIRCODE_PORT`	`port`	`7860` (auto-scan for a new instance)	Port. A persisted or explicitly set busy port fails instead of moving
`AIRCODE_AUTH_PASSWORD`	`authPassword`	generated	Access password. Empty string disables auth (dev only)
`AIRCODE_PROJECTS_ROOT`	`projectsRoot`	launch cwd	Directory whose subfolders are selectable projects
`AIRCODE_MAX_SESSIONS`	`maxSessions`	`32`	Concurrent session cap
`AIRCODE_SESSION_IDLE_TTL_MS`	`sessionIdleTtlMs`	`21600000`	Hibernate completed sessions after 6 idle hours; `0` also disables capacity eviction
`AIRCODE_DEFAULT_PERMISSION_MODE`	`defaultPermissionMode`	`bypass`	Default agent permission mode
`AIRCODE_DEFAULT_EXECUTION_MODE`	`defaultExecutionMode`	`local`	Default session environment (`local` or `docker`)
`AIRCODE_DOCKER_ENABLED`	`dockerEnabled`	`true`	Expose the optional Docker execution backend
`AIRCODE_DOCKER_IMAGE`	`dockerImage`	`aircode-session-runtime:local`	Optional Docker worker image
`AIRCODE_DOCKER_NETWORK`	`dockerNetwork`	`aircode-runtime`	Dedicated worker bridge
`AIRCODE_DOCKER_CONTROL_PORT`	`dockerControlPort`	AirCode Ø port + 1000	Stable capability-scoped worker callbacks
—	`updateChannel`	`stable`	Release channel (`stable` / `beta`)

Session hibernation stops only detached runtimes whose latest turn has a durable completion marker and a resumable transcript. Sessions that are working, awaiting input, remotely controlled, or owned by a workflow stay running. At the session cap, AirCode Ø hibernates the oldest eligible runtime immediately. The conversation remains in History and resumes normally.

Engine binaries (claudeBin, codexBin, …) and per-feature settings (browser, knowledge, orchestration, token optimization) are documented in the in-product settings and accept the same env/file precedence.

See Docker sandbox for worker limits, networking and the complete Docker configuration.

Files & directories

Path	Contents
`~/.aircode/versions/<v>`	the product (immutable, checksummed)
`~/.aircode/current`	symlink to the active version
`~/.config/aircode/config.json`	global user defaults
`~/.config/aircode/instances/<id>.json`	per-instance config, including its password (0600)
`~/.config/aircode/providers.env`	provider credentials shared by the Unix user (0600)
`~/.config/systemd/user/aircode@.service`	one generated systemd template for every managed instance
`~/.local/state/aircode/instances/<id>/`	isolated runtime, tunnel, and session state
`~/.local/state/aircode/relay-account.json`	managed Relay account credential shared by the Unix user (0600)

Updates never touch instance config or state.

Multiple instances

The canonical root determines the default identity. Different roots naturally produce different instances; --name disambiguates multiple instances for one root. Each receives its own port, password/no-password policy, tmux namespace, state, and tunnel identity.

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

Lifecycle commands accept the name, full or short ID, canonical root, or the current directory. A root selector is intentionally rejected as ambiguous when several named instances use it; select the name or ID.

Multi-user machines

Each OS user owns a separate registry, global defaults, provider credentials, managed Relay authorization, and set of systemd user services. Within that user, every path-scoped instance still has its own port, password, state, and sessions. aircode start creates and enables the correct template instance; the older aircode service install command is retained only for compatibility.

License

aircode license activate <key>
aircode license status
aircode license deactivate     # frees the seat for another machine

Offline machines stay fully functional (30-day validation grace; perpetual licenses never phone home). See pricing for what restricted mode means — short version: launching new sessions pauses, nothing else.