Docker sandbox

Preview: Codex sessions on Linux and macOS are the first certified path. Local execution remains available and stays the default. Audited cycles keep their existing Local runtime during this preview.

AirCode Zero keeps its control plane on your computer or server. Choosing Docker sandbox moves only that direct agent session into a short-lived worker container. This is designed for development with bypass permissions: the agent can write to the selected cloned project without receiving the rest of your home directory or the Docker socket.

Web / Desktop / mobile
          ↓
AirCode API + auth + tunnel (host)
          ↓
Local tmux / Windows ConPTY  OR  one Docker worker per session

This is an execution option, not a second containerized AirCode installation. Authentication, session state, notifications, WebSockets, remote access and the UI stay on the host.

Where the choice appears

Web: New session → Execution environment.
Desktop: the same launcher, because Desktop embeds the web workbench.
Native mobile: New session → Execution environment, persisted per saved server connection.
API: POST /api/sessions accepts executionMode: "local" | "docker".

Session details show the effective environment and image. The server validates the daemon, image and engine; it never silently falls back to Local.

Use the source preview today

Docker Engine or Docker Desktop must be running:

git clone https://github.com/spartaquant/aircode.git
cd aircode
npm run docker:runtime:build
npm run docker:runtime:check
npm run docker:session:smoke

Restart AirCode Zero, create a session, then choose Docker sandbox under Execution environment. If Docker or the image is unavailable, the launcher shows the exact reason and does not fall back to Local.

During the preview the image tag is aircode-session-runtime:local. Versioned Docker Hub tags will replace the local development tag after the public repository and release credentials are configured. Until that tag exists, do not try to pull the planned repository name.

When a public tag is available, no AirCode rebuild will be required:

AIRCODE_DOCKER_IMAGE=spartaquant/aircode-session-runtime:<version> aircode

What the worker can access

AirCode does not copy the repository into the image. It mounts the already cloned project at the same absolute path inside the worker. Edits therefore land in the real checkout and remain after the container exits.

Mount	Access	Why
Selected project	Read-write	Code, files and Git checkout
Selected engine profile	Read-write	Authentication, history and native resume
Per-session `/home/aircode`	Read-write	Private temporary home
`/run/aircode` launch contract	Read-only	Command and initial prompt
`/tmp`	In-memory read-write	Temporary files

It does not receive your complete home directory, the Docker socket or host Linux capabilities. The root filesystem is read-only, and Aircode applies PID, memory and CPU controls.

Aircode’s loopback API remains private. A stable, capability-protected control port accepts only the worker’s own completion hooks, including after the Desktop server restarts.

The engine profile contains credentials and is shared read-write in the preview. Container isolation protects unrelated host files; it does not make engine credentials unreadable to the engine or to malicious code running as the same container user.

What happens during a session

The client reads the runtime catalog from the host.
The host validates Docker, the image contract and the selected engine.
AirCode creates one labelled worker and a capability-scoped callback URL.
The worker starts tmux in the mounted project.
The existing terminal WebSocket drives that tmux session through Docker.
Normal exit or Kill session removes the worker, but leaves project changes and engine history on the host.
If AirCode restarts, it rediscovers the worker and restores completion callbacks.

VPN and dev-server traffic

Container egress normally follows Docker’s host routing and NAT rules. A host VPN carries it only when that VPN includes Docker bridge traffic. The managed Hetzner/Aircode tunnel is for inbound access to the Aircode control plane; it does not automatically route worker egress.

Traffic	Route
Phone/browser → AirCode	LAN, VPN or Hetzner tunnel → host
Terminal → worker	host → Docker API → worker tmux
Agent API/Git traffic	Docker bridge/NAT → host VPN policy → Internet
Worker completion hook	worker → protected host callback port

No worker port is published yet. Authenticated dev-server forwarding through Aircode and the Hetzner route is the next networking increment. Local Aircode sessions and existing remote access continue to work unchanged.

Preview limits

Codex is the first certified engine. The image contains the other pinned CLIs for compatibility testing, but the launcher keeps them unavailable in Docker.
Direct sessions are covered. Audited cycles continue to use Local execution.
Linux and macOS hosts are targeted. Windows Desktop keeps native ConPTY Local sessions; Docker path semantics are not certified there yet.
Host browser capabilities and external token-optimization wrappers are not injected into workers yet.

Configuration

Environment variable	`config.json`	Default	Purpose
`AIRCODE_DEFAULT_EXECUTION_MODE`	`defaultExecutionMode`	`local`	Default launcher environment
`AIRCODE_DOCKER_ENABLED`	`dockerEnabled`	`true`	Docker feature switch
`AIRCODE_DOCKER_BIN`	`dockerBin`	`docker`	Docker CLI
`AIRCODE_DOCKER_IMAGE`	`dockerImage`	`aircode-session-runtime:local`	Worker image
`AIRCODE_DOCKER_NETWORK`	`dockerNetwork`	`aircode-runtime`	Dedicated bridge
`AIRCODE_DOCKER_CONTROL_PORT`	`dockerControlPort`	AirCode port + 1000	Capability-scoped hook bridge
`AIRCODE_DOCKER_ENGINES`	`dockerEngines`	`codex`	Fallback certified-engine list
`AIRCODE_DOCKER_PIDS_LIMIT`	`dockerPidsLimit`	`512`	Per-worker PID limit
`AIRCODE_DOCKER_MEMORY`	`dockerMemory`	`8g`	Per-worker memory limit
`AIRCODE_DOCKER_CPUS`	`dockerCpus`	unset	Optional CPU limit

Keep the callback port stable while workers are running. See Troubleshooting for the runtime error codes.

The Docker daemon remains a trusted host component. Anyone who controls that daemon can bypass container isolation.