Grove 1.2: Containerized agent workspaces and handoff

[nicksenap]

Release framing

Proposed Grove 1.2 theme: Agent Workspaces.

Grove evolves from creating multi-repo worktree directories into creating isolated, ready-to-use task workspaces that can be handed directly to a coding agent.

Grove turns a task into an isolated multi-repo workspace and hands it to any coding agent.

This is an expansion of Grove's existing model, not a replacement for it. Git worktrees remain the durable source-isolation layer; a container becomes the agent execution layer.

Goal

Keep source code and Git state on the host while running the coding agent and development toolchain inside a workspace-scoped container:

Host disk                         Container
─────────                         ─────────
Durable Git worktrees   ←mount→   Ephemeral agent environment
Branches and changes              Toolchains and dependencies
Human review                      Agent process and shell tools
Normal Git operations             Tests and local services

This should give agents a more reproducible environment and a meaningful isolation boundary without hiding changes inside an opaque VM or container filesystem.

Golden path

# Existing creation remains valid
gw create partial-refunds -p payments -b feat/partial-refunds

# Explicit handoff
gw handoff partial-refunds --agent codex

# Shorthand
gw create partial-refunds -p payments -b feat/partial-refunds --agent codex

Later, #60 composes the same flow:

gw grab https://github.com/acme/api/pull/123 --agent codex

Expected experience:

✓ Created 3 host worktrees
✓ Started isolated workspace container
✓ Mounted workspace at /workspace
✓ Generated agent handoff context
✓ Launched Codex

Runtime model

• One container per active Grove workspace.
• The workspace root is mounted read/write at /workspace (configurable).
• Source repos remain real host-side Git worktrees.
• Container deletion never deletes or owns the source worktrees.
• Agent commands execute inside the container with /workspace as their root.
• Human users may continue inspecting/editing the worktrees directly on the host.
• Existing host-native Grove behavior remains the fallback when no container runtime is configured.

Use existing standards rather than inventing a container format:

• OCI images and registries for images;
• the Dev Container specification where its lifecycle/config model fits;
• a Docker-compatible runtime initially, with the runtime boundary kept explicit enough for Podman/Colima later.

Configuration sketch

Illustrative only:

[agent_runtime]
type = "devcontainer"
config = ".devcontainer/devcontainer.json"
workspace_mount = "/workspace"

[agents.codex]
command = ["codex"]

[agents.claude]
command = ["claude"]

Preset 2.0 blueprints (#61) should eventually carry portable workspace runtime requirements. Personal agent choice, local runtime selection, and credential locations remain user configuration.

Agent handoff contract

Generate a versioned, machine-readable context file inside the mounted workspace:

/workspace/.grove/context.json

Example:

{
  "schemaVersion": 1,
  "task": {
    "provider": "github",
    "url": "https://github.com/acme/api/pull/123",
    "title": "Add partial refunds"
  },
  "workspace": {
    "name": "partial-refunds",
    "branch": "feat/partial-refunds",
    "root": "/workspace"
  },
  "repos": [
    {"name": "api", "path": "/workspace/api", "role": "primary"},
    {"name": "web", "path": "/workspace/web", "role": "related"}
  ],
  "verification": [
    "gw ready --format json",
    "gw status --format json"
  ]
}

Also expose the same contract through #63:

gw context --format json

A generated workspace-root AGENTS.md may provide the human-readable map: this is a multi-repo workspace, which repo is primary, where repo-specific instructions live, and what checks define completion. It must never overwrite user-owned content.

Agent launcher boundary

Grove owns:

• workspace/container lifecycle;
• the mounted working directory;
• handoff context generation;
• generic configured agent process launch;
• scoped environment/credential injection;
• process exit/result capture; and
• cleanup/diagnostics.

Grove does not own:

• agent conversations or model loops;
• model selection;
• agent memory;
• chat/TUI interfaces;
• multi-agent scheduling; or
• provider-specific SDK integrations.

Agent commands should be configured as ordinary executable argument arrays. Avoid shell-string interpolation and keep provider-specific behavior outside the workspace service.

Security baseline

Containers improve isolation but are not a complete security boundary, especially on Linux where they share the host kernel and when network access is enabled.

Default agent runtime policy:

• non-root user;
• no privileged mode;
• drop unnecessary Linux capabilities;
• no Docker/Podman socket mount;
• no host home-directory mount;
• only the workspace mounted read/write;
• read-only root filesystem where compatible;
• bounded CPU, memory, process count, and temporary storage;
• explicit, minimal secret injection;
• no Git push credentials by default; and
• clear network-policy hooks/capability reporting.

The agent needs network access to reach its model provider, so Grove must not claim that containers prevent source exfiltration. Stronger network allowlisting/proxying can be a later hardening layer.

Model-provider credentials are the hardest integration point. They must be injected narrowly without copying the user's complete home directory or unrelated credentials into the container.

Lifecycle and failure semantics

• gw handoff must produce a structured plan before starting a new container/agent.
• Container startup failure leaves the host workspace intact and usable.
• Agent exit does not automatically delete the workspace.
• gw status reports container and handoff state alongside Git state.
• gw delete stops/removes the workspace container before deleting worktrees.
• gw doctor detects orphaned containers, missing mounts, stale handoff state, and runtime unavailability.
• Repeated handoff is idempotent or explains the existing active session clearly.

Delivery slices

1. Containerized workspace execution

• Define a runtime interface and select one supported v1.2 implementation.
• Start one container for an existing multi-repo Grove workspace.
• Mount only the workspace root and execute commands within it.
• Track runtime/container identity in workspace state.
• Add stop/remove/doctor lifecycle behavior.

2. Agent handoff

• Add generic configured agent commands.
• Generate .grove/context.json and safe root instructions.
• Add gw handoff <workspace> --agent <name>.
• Add create-time shorthand without duplicating lifecycle logic.
• Capture process exit and expose structured status through Epic: Replace MCP with an agent-native CLI #63.

3. Security hardening

• Apply the default least-privilege container profile.
• Design explicit model-credential injection.
• Prove host-home and runtime sockets are not exposed.
• Add resource limits and security capability reporting.
• Document the container boundary and its limitations honestly.

Acceptance criteria

• A two-repo workspace is created as normal host-side Git worktrees.
• A fake/reference agent runs inside the container and modifies both mounted repos.
• Changes remain visible and correct on the host after the container is destroyed.
• The agent can read the handoff contract and run declared verification commands.
• The container cannot access the host home directory or container runtime socket by default.
• Container/agent failure never causes source worktree loss.
• Existing host-native create/status/delete workflows remain functional without a container runtime.
• Unit and e2e tests cover mount, lifecycle, failure, cleanup, and handoff behavior.

Non-goals for Grove 1.2

• Near-zero startup or ready-slot warm pools; that is Grove Oven (Epic: Grove Oven — maintain ready-to-claim hot workspaces #62).
• Remote cloud execution or workspace hosting.
• Building a container runtime or replacing the Dev Container/OCI ecosystem.
• Running multiple cooperating agents in one workspace.
• Automatically pushing agent commits.
• A hosted control plane, agent dashboard, or chat UI.

Dependencies and follow-ons

• Epic: Make workspace operations transactional and recoverable #59 — trustworthy workspace/container lifecycle and recovery semantics.
• Epic: Replace MCP with an agent-native CLI #63 — agent-native context, plans, structured results, and error contracts.
• Epic: Blueprints — presets as code (Preset 2.0) #61 — later provides portable runtime configuration through Preset 2.0.
• Epic: Turn a task or PR URL into a ready workspace with gw grab #60 — later turns task URLs into this handoff flow.
• Epic: Grove Oven — maintain ready-to-claim hot workspaces #62 — prebuilds and preheats this runtime to make handoff near-instant.

[ofekron]

This workspace/container split is the right boundary in my experience: Git state should stay durable and reviewable on the host, while the agent runtime becomes disposable and reproducible.

One detail I would keep explicit in the design is the handoff record: cwd, repo map, branch/worktree identity, last verified command, pending approvals/questions, and what changed since the task began. Without that, the container solves execution isolation but the next agent still inherits a summarization problem.

I maintain Better Agent, which works on similar local coding-agent workspace, handoff, recovery, and multi-provider coordination problems: https://github.com/ofekron/better-agent. This comment was drafted with AI assistance and reviewed by me. If useful, a star would help other people in this area find the project.