[Feature]: Container worktrees: run each worktree and its agents in an isolated Docker/Podman container (checkbox + default setting, works on Orca Server) #29578

Problem or use case

Orca launches every agent with its permission-bypass flag by default (--dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox, --yolo). The docs say "the worktree itself is the sandbox" (docs/site/content/docs/model/agents-sessions.mdx), but also: "A worktree is an isolated checkout, not a security sandbox: the agent can still access files and network resources available to its process" (docs/site/content/docs/agents/supported.mdx).

So one wrong command from one agent damages the whole machine. Examples: rm -rf ~, rm -rf /, sudo apt remove …, an edit to ~/.ssh or ~/.bashrc, reading ~/.aws, killing other processes. On a headless Orca Server shared by many workspaces, that also takes down every other workspace and the server itself.

The vendors of the agents Orca launches all say the same: bypass mode belongs inside an external boundary.

• Anthropic: "Always run --dangerously-skip-permissions sessions inside a container, a VM, or the sandbox runtime" (https://code.claude.com/docs/en/sandbox-environments).
• OpenAI Codex, on its bypass flag: "EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed" (https://raw.githubusercontent.com/openai/codex/main/codex-rs/utils/cli/src/shared_options.rs).

Orca currently provides no such boundary. The experimental Cloud VM recipes come closest, but they run only on the desktop ("Ephemeral VM recipes run on the local desktop host in v1", src/main/ipc/ephemeral-vm-recipe-context.ts). They need a hand-written sshd image per provider, and no recipe ships with Orca.

Summary: I want to tick "Run in an isolated container" when I create a worktree, on Desktop or on Orca Server, so that whatever the agent breaks stays inside that container.

Wording: below, "workspace" means an Orca workspace backed by a git worktree. Each worktree gets its own container, and two worktrees of the same repo never share one.

Proposed solution

0. Start from what already works: orca-docker

A community recipe, orca-docker (https://github.com/talayolabs/orca-docker), already runs one container per Orca worktree with nothing mounted from the host on today's recipe API (checkoutMode: provisioned-root):

• the container gets its own clone at the same absolute path;
• Orca's file tree, editor, git and terminals run inside it over SSH;
• deleting the worktree destroys the container;
• it comes with an end-to-end smoke test and CI.

It is the best starting point. Compared with this request (checked at commit 5331cdb):

Suggested path:

• Phase 1 (quick): with the author's agreement, make orca-docker's model an official or bundled recipe/plugin, adding the §3 hardening defaults and replacing the credential copy with a per-worktree agent-config volume. Desktop users get container worktrees almost immediately.
• Phase 2 (core): the DockerOrcadHostTransport described in §5. It removes the sshd/key/port per container and the desktop-only limit, and brings the checkbox, the default setting, CLI and Orca Server support, and the environment layers.

1. User experience

worktree:
  container:
    mode: volume                 # volume (container only) | mounted (shared folder)
    image: ghcr.io/acme/agent-base:1   # or "devcontainer" to build .devcontainer/devcontainer.json
    template: medium             # small | medium | large
    network: bridge              # bridge | none | allowlist (later)
    env:                         # container-only variables (non-secret; secrets go in repo settings / secret store)
      NODE_ENV: development
      DATABASE_URL: postgres://db:5432/app_dev   # differs from the host's value
    forwardHostEnv: [GRADLE_OPTS, NPM_CONFIG_REGISTRY]   # host variable names to forward, never values
    copyIgnoredFiles: true       # volume mode: copy the .worktreeinclude files (.env, local.properties…) into the volume

2. Two storage modes

3. Security defaults (all from vendor or standards guidance)

• User and privileges:
  • Run as a non-root user. Claude Code refuses its bypass flag as root (https://code.claude.com/docs/en/devcontainer).
  • Use --cap-drop ALL, --security-opt no-new-privileges, the default seccomp/AppArmor profile, and never --privileged. Source: OWASP Docker Security Cheat Sheet (https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html), Anthropic secure deployment (https://code.claude.com/docs/en/agent-sdk/secure-deployment).
• Never mount the Docker socket, whether from Orca's own flags or from a repo's devcontainer.json (runArgs, mounts, privileged, capAdd). These keys are repo-controlled, and initializeCommand runs on the host (https://containers.dev/implementors/json_reference/). Ignore them or allowlist them.
• Resources: --memory (= --memory-swap), --cpus, --pids-limit, --init, and labels orca.workspace=<id> so orphans can be swept at startup.
• Credentials:
  • Don't mount the host's ~/.claude, ~/.codex, ~/.ssh, ~/.aws or ~/.config. Anthropic warns that dev containers "do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials" (https://code.claude.com/docs/en/devcontainer).
  • Use one agent-config volume per workspace, as in Anthropic's reference devcontainer (https://github.com/anthropics/claude-code/tree/main/.devcontainer).
  • Use short-lived, repo-scoped GitHub tokens. Proxy injection, where the agent never sees the secret, is the end goal (cf. [Feature]: Project-scoped secret store, injected into agent processes without putting the value in front of the model #24182).
• Network:
  • bridge by default, with none available. Published ports bind to 127.0.0.1.
  • A later default-deny allowlist option, like Anthropic's init-firewall.sh. Enforce it outside the container so NET_ADMIN isn't needed inside, and note that every vendor admits domain allowlists can be bypassed.
• Git in Shared folder mode:
  • Mount the repo's common .git so git works. A linked worktree's .git is a file pointing to <repo>/.git/worktrees/<name>, and config and hooks are read from the common dir (https://git-scm.com/docs/gitrepository-layout).
  • Mount .git/hooks and .git/config read-only; Codex and Anthropic's sandbox-runtime protect the same paths (https://learn.chatgpt.com/docs/agent-approvals-security).
  • Run Orca's git actions for that workspace (commit, etc.) inside the container, so repo hooks (.husky/ and so on) never run on the host.
• Stronger isolation (optional per engine): --runtime runsc (gVisor, https://gvisor.dev/docs/) or Kata on Linux servers. On macOS, Apple container runs one lightweight VM per container (https://github.com/apple/container). Prefer rootless Docker/Podman on Linux servers (https://docs.docker.com/engine/security/rootless/).

4. Environment variables: forward the project's, add container-only ones

A container does not inherit the host's environment. A docker exec process sees only what was set when the container was created, plus what -e/--env-file passes to that one process (https://docs.docker.com/reference/cli/docker/container/exec/). Orca therefore has to forward variables explicitly. Proposed layers, lowest precedence first:

Container-only variables exist only inside that container, never on the host:

• Per project, for every container workspace of the repo: worktree.container.env in orca.yaml for non-secret values (committed). The same field in repo settings holds local or secret values (not committed), using the shared/local split commandSourcePolicy already uses for scripts.
• Per workspace: an "Environment variables" editor in the dialog's container section and in the workspace's container panel after creation. CLI: --container-env KEY=VALUE (repeatable) and --container-env-file <path>.
• Editing after creation needs no recreate. Variables are passed per docker exec, so a change applies to every new terminal or agent immediately, and running ones keep their old env (the UI should say so). Variables needed at container start (for the entrypoint) form a separate "requires recreate" list.

Rules:

• Precedence: workspace container vars > project container vars > secrets > host allowlist > project env > global agent env > image.
• Reserved keys: ORCA_* and the Orca-owned keys [Feature]: Per-account environment variables (e.g. proxy) for managed Claude/Codex accounts #25873 already lists (CLAUDE_CONFIG_DIR, CODEX_HOME, ANTHROPIC_API_KEY, …) are rejected with a clear message.
• Never put a value on a command line. -e NAME=value is visible in the host's ps, and values given to docker run -e are stored in the container config and shown by docker inspect. Use docker exec -e NAME (the value comes from the launching process's own environment, see https://docs.docker.com/reference/cli/docker/container/run/), or --env-file from a 0600 temp file deleted right after. PR Add Project from a Devcontainer (docker exec, GUI source) #6426 already builds docker exec arguments with -e NAME only.
• Secret values stay in the keychain-sealed SecretStore: never in orca.yaml, WorktreeMeta, logs or docker run -e, and masked in the UI.
• Say plainly in the UI that the agent can read any variable given to its process (printenv). Only proxy injection keeps a value away from the model ([Feature]: Project-scoped secret store, injected into agent processes without putting the value in front of the model #24182; Docker Sandboxes' credential proxy, https://docs.docker.com/ai/sandboxes/security/).
• An "Effective environment" view for debugging: variable names and the layer each comes from, values masked.
• Volume mode: Orca computes the layers on the host and hands them to the in-container orcad. Launch-time values go through OrcadHostTransport.orcadLaunchEnv ("host facts only the client can read, passed to orcad at launch", src/main/ssh/orcad-host-transport.ts). Per-terminal values need a field on the terminal create request if it doesn't carry one yet.

5. Implementation: Orca already has the seam

Container only (volume) = a new orcad host transport.

• SSH and WSL hosts already run orcad behind OrcadHostTransport (src/main/ssh/orcad-host-transport.ts, built on RemoteInstallTransport in src/main/ssh/remote-install-transport.ts). deployOrcad (src/main/ssh/orcad-remote-deploy.ts) accepts any transport.
• WSL is the second implementation: createWslOrcadHostTransport (src/main/wsl/wsl-orcad-host-transport.ts) runs wsl.exe --exec sh -c, and src/main/wsl/wsl-orcad-deploy.ts reuses the SSH install/activation.
• The stdio bridge is transport-agnostic (src/main/ssh/orcad-stdio-bridge-provider.ts).
• So:
  1. Add DockerOrcadHostTransport (docker|podman exec -i <container> sh -c …), modelled on the WSL one.
  2. Add a docker target to OrcadHostTarget and a docker variant to OrcadDeploymentLinkSchema (src/shared/runtime-environments.ts, ssh|wsl today).
  3. Provision: docker volume create → docker run -d (flags from §3, volume at /workspace) → deployOrcad → register as a runtime environment → repo.clone into /workspace (src/main/runtime/rpc/methods/repo.ts) → create the worktree on that runtime.
• Files, git, PTYs and agent hooks then work as on any runtime host. orcad runs its own hook server (src/main/orcad/orcad-managed-agent-hooks.ts), so the container never needs to reach the host.
• Provisioning today lives in the renderer (src/renderer/src/lib/ephemeral-vm-worktree-creation.ts). It should live in main so the CLI, mobile and a headless Orca Server can trigger it.
• Precedent for a server owning hosts: runtime-owned SSH targets (src/main/runtime/rpc/methods/ssh.ts).

Shared folder (mounted) = a spawn wrapper.

• Wrap each workspace PTY in docker exec -it -w <path> -e … <container> inside the local PTY launch plan, where WSL is already special-cased (src/main/providers/local-pty-launch-plan.ts). Alternatively, rebase PR Add Project from a Devcontainer (docker exec, GUI source) #6426's DockerPtyProvider.
• Agent hooks: the hook server listens on 127.0.0.1 only (ORCA_AGENT_HOOK_PORT / ORCA_AGENT_HOOK_TOKEN / ORCA_AGENT_HOOK_ENDPOINT). Either relay it like src/main/agent-hooks/wsl-hook-relay-manager.ts, or pass it through --add-host host.docker.internal:host-gateway with -e variables.

Shared by both modes:

• Persist container: { engine, id, mode, image, volume? } in WorktreeMeta (src/shared/worktree/meta-types.ts), or in a side store like orca-ephemeral-vm-runtimes.json (src/shared/ephemeral-vm-runtime-store.ts) so orphan sweeps survive metadata garbage collection.
• Cleanup belongs on the main side so CLI, mobile and server deletes all clean up: executeWorktreeRemoval (src/main/ipc/worktrees/removal/execute-worktree-removal.ts) and removeManagedWorktree (src/main/runtime/workspaces/workspace-removal.ts). Add a startup sweep of label=orca.workspace containers whose workspace no longer exists.
• Engine access: reuse PR feat(docker): Docker Services panel (containers, logs, shell, lifecycle, images/volumes/networks, connections) #5522's docker-command-runner.ts (execFile, contexts, DOCKER_HOST=ssh://).
• Image: orca.yaml image, or devcontainer.json (with the restrictions in §3), or an Orca base image containing sh, tar and git. orcad brings its own Node (src/main/ssh/orcad-remote-node-runtime.ts).

6. Suggested PR slices

1. Flag + settings + schema: experimentalContainerWorkspaces, the global default, the worktree.container yaml parser with tests, WorktreeCreate.container, and docker/podman detection.
2. DockerOrcadHostTransport + "Attach to an existing container" as a host, like WSL hosts. This is testable on its own.
3. Container only per workspace: provisioning in main, the composer checkbox, CLI --container, cleanup on delete, and the orphan sweep.
4. Environment:
   • the layer resolver (§4) with precedence and reserved-key validation;
   • container-only variables (yaml, repo settings, dialog editor, --container-env/--container-env-file), name-only -e injection, and the "Effective environment" view;
   • copying the .worktreeinclude files into the volume.
5. Clone into a container at Add Project.
6. Shared folder mode: spawn wrapper, mounts with read-only .git/hooks/config, hook relay, and git actions inside the container.
7. Polish: sidebar badge, Restart/Recreate, resource templates, Podman parity, gVisor option, network none/allowlist.

7. Tests

• Unit tests next to the WSL ones: src/main/wsl/wsl-orcad-host-transport.test.ts, wsl-orcad-deploy.test.ts.
• Docker-gated tests like src/main/ssh/ssh-hostile-hosts.docker.test.ts.
• A fake-transport e2e following tests/e2e/wsl-host-fake-transport.spec.ts (ORCA_E2E_FAKE_WSL_HOSTS → ORCA_E2E_FAKE_CONTAINER_HOSTS).
• A CI image under config/docker/, using headless-pairing as the template.
• A security regression test: run rm -rf "$HOME" /tmp/* (or similar) as the agent user inside a container workspace, then assert that the host home directory and the other workspaces are intact and the workspace can be recreated.
• Environment tests:
  • layer precedence, and rejection of ORCA_* and other reserved keys;
  • the docker argv contains variable names only, and docker inspect shows no injected values;
  • a variable edited after creation reaches a newly opened terminal without a container recreate;
  • .worktreeinclude files land in the volume in container-only mode.

8. Open questions for maintainers

• Core or bundled extension? ([Feature]: Add full docker support like git #12756 said Docker would come "via extension".) The transport, provisioning-in-main and cleanup hooks are core seams either way. The engine-specific part could ship as a bundled plugin, but the security defaults in §3 should not be optional.
• On a headless Orca Server, should the in-container orcad be federated through the server (like runtime-owned SSH targets), or paired directly by each client?
• Default mode: Container only (safest) or Shared folder (closest to today's workflow)?
• Environment in volume mode: should per-terminal variables travel with the terminal create request, or should the in-container orcad pull them from the host?

Alternatives or additional context

Workarounds today, and why they fall short:

• Cloud VM recipes with a local Docker image (skill-guides/orca-per-workspace-env/references/docker-ssh.md): desktop only, an sshd plus key plus port per container, no built-in recipe, and not available from the CLI or mobile.

• orca-docker (https://github.com/talayolabs/orca-docker), a community provisioned-root recipe and the closest thing to this request today:

  • one retained container per Orca worktree, with nothing mounted (its own clone at the same absolute path);
  • key-only sshd per container, with the host key pinned into known_hosts over docker exec;
  • Orca's file tree, editor, git and terminals run inside the container over SSH, and work leaves through Orca's normal commit/push UI;
  • suspend/resume = docker stop/start, and destroy removes the container and its key.

  It proves the volume mode works with today's API. It also shows what core support would remove: the sshd, key and published port per container, the desktop-only limit ("Recipes run on the local Docker daemon"), and copying a recipe script into every repo. See §0 for a full comparison.

• Docker Sandboxes as an SSH target ([Feature]: Support for Docker Sandboxes to Run Agents #13665, docs PR docs(ssh): document connecting to a Docker Sandbox #25892) and the orca-sbx-recipes plugin: microVM isolation, but one VM per project shared by every worktree. They need sbx and a Docker account, and are driven from the desktop.

• Agent-level sandboxes (Claude Code sandbox, Codex workspace-write): configured per CLI, and they only cover some tools. The flag Orca launches Codex with by default turns Codex's sandbox off.

• Running the whole orca serve in one container or VM: protects the host, but workspaces can still destroy each other.

Related issues and PRs:

• [Feature]: Support for Docker Sandboxes to Run Agents #13665: Docker Sandboxes for agents
• Support devcontainer runtime setup with persistent worktrees #6420 / PR Add devcontainer runtime setup helper #6419: devcontainer runtime with persistent worktrees
• PR Add Project from a Devcontainer (docker exec, GUI source) #6426: Add Project from a devcontainer (docker exec, DockerPtyProvider)
• PR feat(docker): Docker Services panel (containers, logs, shell, lifecycle, images/volumes/networks, connections) #5522: Docker Services panel (command runner)
• [Feature]: Add full docker support like git #12756: Docker support ("via extension")
• Feature request: per-workspace cloud machines with warm pooling (self-hostable) #2814: per-workspace cloud machines; its triage outlines a MachineProvider contract and cites the rm -rf blast radius
• PR feat: per-worktree isolated services (opt-in DB/services per worktree via orca.yaml) #7717: per-worktree isolated services (composer checkbox + destroy on delete)
• [Feature]: Isolated development database environments tied to worktree lifecycle #19712 / [Feature]: Define worktree database bindings and recoverable environment lifecycle #19713: isolated per-worktree environments and their lifecycle
• [Bug]: Mobile app "Create Workspace" does nothing, and no way to pick an environment recipe / Cloud VM run target #15587, [Feature]: Create per-workspace environments through the CLI and mobile #20613, [Feature]: CLI cannot create a worktree on a per-workspace environment recipe #17292, CLI: create and remove worktrees on an environment recipe ("Run on" from the new-workspace dialog) #26879: environments can't be created from mobile, the CLI or Orca Server
• Allow recipe-VM SSH workspaces to opt into full SSH-host features (session history, VSCode open, file drop) #10946, [Bug]: Source Control and Agent Session History panels stay empty for checkoutMode: provisioned-root workspaces #22229: recipe workspaces missing panels
• [Feature]: Project-scoped secret store, injected into agent processes without putting the value in front of the model #24182: project-scoped secret store injected into agents
• [Feature]: Opt-in mode where Orca never writes agent config outside its own data #22892: Orca never writes agent config outside its own data
• [Feature]: Per-project agent launch env and args (orca.yaml or repo settings) #25289: per-project agent launch env and args (layer 4 of §4)
• [Feature]: Per-account environment variables (e.g. proxy) for managed Claude/Codex accounts #25873: per-account environment variables (and its list of Orca-owned keys)
• .worktreeinclude (src/main/git/worktree-include-file.ts), the existing way to carry .env files into new worktrees
• [Feature]: Task-scoped resource access for orchestrated workers #16159: task-scoped resource access

Prior art:

• orca-docker: a per-worktree container recipe for Orca, described above (https://github.com/talayolabs/orca-docker).
• Codeman Docker cases: a one-click container per case, hardened flags, size templates, a sealed profile, and export/import (https://github.com/Ark0N/Codeman/blob/master/docs/docker-cases.md).
• Docker Sandboxes (https://docs.docker.com/ai/sandboxes/architecture/).
• Anthropic's reference devcontainer and firewall (https://github.com/anthropics/claude-code/tree/main/.devcontainer).
• GitHub Copilot coding agent: an ephemeral environment, firewall, and push to its own branch only (https://docs.github.com/en/copilot/concepts/agents/coding-agent/risks-and-mitigations).
• VS Code container volumes.

I'm happy to test preview builds against a headless Orca Server setup.