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`	`64`	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. For one root, a different explicit port creates or reuses an independent automatically named instance rather than changing and restarting the default. --name supplies a stable role-oriented identity when you want one. Each instance receives its own port, password/no-password policy, tmux namespace, state, and tunnel identity.

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

To change an existing instance’s port, select that instance explicitly by name or ID. A root-scoped command with a new port is intentionally treated as a new instance so it cannot silently take the current server offline.

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.

Free product access

The self-managed product requires no product key, activation, card, or trial. It stays fully usable offline and does not restrict session launches when an old license or trial record expires.

The aircode license command is retained only so historical installations can inspect or remove legacy records. Those records do not change current product access. See Download for the separate account requirements of managed Relay and Marketplace actions.