Containerized Agents

Give each agent an isolated environment

A container workspace gives one agent its own stack. Docker in Docker, a database, services, ports, none of them yours.

Agents in their own stack

• You own the repo, in committed .devcontainer/ and Grove config.
• Grove owns the boundary.
• The agent runtime owns the work, ungated.
• Twenty agents spawning tests and builds turn into a number you set, instead of a saturated machine.

Host or container

Runtime is a per workspace choice, so two workspaces in one repo can differ.

What the container is for

• Permission prompts are the host's safety mechanism. The container is the mechanism for claude --dangerously-skip-permissions or Codex full auto.
• The reachable set shrinks to the worktree, the mounts and the nested docker daemon. Not another workspace, not your dotfiles, not the host engine.
• It is a blast radius boundary, not a credential boundary. Under the default share: full your credentials are mounted in, so set share: isolated for an untrusted repository.

How the runtime gets chosen

Grove selects the runtime at creation.

flowchart LR
    A["grove create"] --> B{"--runtime"}
    B -->|host| H["Host<br/>workspace"]
    B -->|"container<br/>(default)"| C{"Runtime<br/>ready?"}
    C -->|no| F["Host, with a<br/>persistent warning.<br/>Fix, then respawn."]
    C -->|yes| D{".devcontainer/<br/>in repo?"}
    D -->|yes| E["Your config.<br/>The one<br/>VS Code reads."]
    D -->|no| G["Grove's packaged<br/>default. Still<br/>full isolation."]
    E --> Z["Agent runs in<br/>the container"]
    G --> Z

• Container is the configured default, and every create surface shows the choice.
• A repo with a .devcontainer/ gets its own config, the one VS Code reads. A repo without one gets Grove's packaged default, still isolated.
• A missing Docker or devcontainer CLI is caught before Grove touches the filesystem. The workspace lands on the host with a warning naming the remedy, and grove respawn promotes it later.
• An explicit --runtime host is your decision, so Grove never promotes on its own.

Where your code lands

Grove bind mounts the worktree instead of cloning it, so the container edits the same files your host sees.

• The default container path is /workspaces/<worktree-directory-name>, and that is the agent's working directory.
• Your own workspaceFolder wins when the devcontainer sets one, and Grove translates the paths the CLI reports.

"workspaceMount": "source=${localWorkspaceFolder},target=${localWorkspaceFolder},type=bind",
"workspaceFolder": "${localWorkspaceFolder}"

Sessions outlive your terminal

The agent runs under tmux inside the container, not your host tmux, so your host session is only a viewport.

• Detach, close the terminal, restart the daemon, or let your host tmux die. The container owns the terminal and the work continues.
• grove attach returns you mid task with its scrollback, and grove respawn rebuilds the viewport, not the agent.
• A detached workspace stays observable, since peek, the webapp terminal and steering read its own pane.
• grove shell WORKSPACE goes straight to a prompt inside the container, trying the shells in container.shell in order.
• Grove brings its own static tmux and terminfo when the image ships none, the same way it brings iptables.

Reading the container status line

Grove bind mounts read only terminal assets at /grove/decor, so attach shows a status bar instead of bare default chrome.

Several agents in one container

A workspace runs one agent. For a second, say a reviewer reading what the first wrote, start it in the same container.

• grove agent add WORKSPACE --agent codex --name reviewer gives it its own persistent tmux session, only when you ask.
• grove agent list, attach, peek, message and kill manage them.
• They share the worktree, branch and container, which is the point and the caveat. Two agents editing the same files collide like two people would.
• A host workspace holds one agent only.

Opening it in VS Code

grove code WORKSPACE opens VS Code's editor inside the container.

• Source stays on the bind mount and build artifacts stay in the container's own volumes.
• The editor's server runs inside too, so a container built node_modules never confuses a host language server.
• Cursor and VSCodium cannot open it this way, since Dev Containers is proprietary. grove shell and grove attach are the way in.

Start from the devcontainer you already have

A repository devcontainer is used as it stands, and grove doctor checks the tools it needs.

grove create "fix login" --agent claude                      # configured default
grove create "fix login" --agent claude --runtime container
grove create "fix login" --agent claude --runtime host

Getting secrets and environment in

Choose one source for container secrets.

container.env_file: ".env.grove"                    # pick one
container.env_command: "./scripts/print-secrets.sh" # or the other

Extending the environment

A container workspace accepts the devcontainer specification.

grove init devcontainer scaffolds the default, and the later tiers are where frequent changes belong.

Setting the limits

Three settings control sharing, network access, and resources.

container.agent_config.share: full | projects | isolated   # default: full
container.egress.mode: allowlist | open | deny             # default: allowlist
container.resources: { memory: "8g", cpus: 4, pids: 2048 }

Grove init scripts and container hooks

A Grove init script prepares the host worktree first, then the devcontainer's own hooks run inside. init_script.applies_to: "host" stops it running twice when your hooks already install what it would. all is the default and container is the other value.

Configuration reference

Full schema on the configuration reference page.

See also

• Workspace lifecycle covers respawn.
• CLI lists the container commands.