Guide

Frequent Questions

Short answers to questions that come up often.

Sandbox

How to customize

At two layers: the project image (declared in overplane.yaml, rebuilt with overplane sandbox build) and the individual run (flags on overplane sandbox run). The full breakdown lives in Customizing the environment in the advanced topics guide.

Can an agent modify my project?

No. The project tree is mounted read-only at /project (and specs at /specs) in every sandbox and every build phase, so nothing inside the container can mutate your working copy. Agents write to fresh scratch mounts (/output, /error, and /code during codegen), and generated files are reconciled back to the host only after a successful run. A read-write project tree is a deliberate non-feature. The full matrix is in the mounts reference.

Do I need Docker, or does Podman work?

Either works, and behavior is identical on both. Set sandbox.runtime in overplane.yaml to pick the engine per project, or override it per run with --runtime. Docker requires Buildx/BuildKit 0.13 or newer; Podman is supported at 5.x. Details are in the container runtimes reference.

How do agent API keys get into the sandbox?

From your host environment, at run time. Each agent recipe configured in overplane.yaml forwards its backend's key variables (for example ANTHROPIC_API_KEY for Claude Code) into the container automatically, and sandbox.env_passthrough forwards any additional variables you name. Keys travel as runtime environment variables, not image layers, so the image you build and share stays free of secrets.