Workspaces

Decapod workspaces are isolated execution environments that ensure agentic work is performed safely and reproducibly.

The Isolation Hierarchy

Decapod provides three levels of isolation:

  1. Branch Isolation: Every task is performed on a dedicated git branch, preventing accidental mutations to main.
  2. Filesystem Isolation: Decapod uses Git Worktrees to create unique directory structures for every task. This allows multiple agents to work on the same repository concurrently without filesystem collisions.
  3. Process Isolation: By enabling container_workspaces, Decapod wraps each worktree in a Docker container. This ensures that an agent's processes, environment variables, and local dependencies (like node_modules) are completely isolated from other agents.

Workspace Lifecycle

  • Acquisition: Triggered by decapod workspace ensure. Decapod calculates the necessary isolation level based on project config.
  • Entry: The agent cds into the workspace. All subsequent tool calls (compilers, linters, tests) must be executed within this boundary.
  • Promotion: Once work is verified, decapod workspace publish bundles the changes for merging back into the root repository.
  • Eviction: Completed or abandoned workspaces are automatically cleaned up to save disk space and maintain repository hygiene.

Why it Matters

Without workspace isolation, multi-agent systems are prone to "environment drift" and race conditions. Decapod's workspace model makes concurrent agent work as safe as concurrent human work on separate machines.