Definition
A shadow fork is an isolated workspace—branch, repo fork, or sandbox environment—where an agent can run commands and experiment without contaminating mainline code or production systems.
It’s a safety rail for agentic execution.
Why it matters
The dangerous part of agents isn’t “they write bad code.” It’s “they run commands in the wrong place.”
Shadow forks give you:
- containment for mistakes,
- separation for credentials,
- and predictable cleanup.
Common implementations
- Ephemeral git branches per agent (delete on completion)
- Forked repo with restricted permissions
- Preview deployments with limited env vars
- Containerized dev shells with no network / no secrets
What to enforce in a shadow fork
- Least-privilege credentials (or none)
- No ability to push to protected branches
- Clear artifact boundaries (what can be exported back)
- Mandatory receipts (build receipt)
Relationship to trust
A shadow fork doesn’t replace the trust boundary. It makes it cheaper to enforce:
- agents can run aggressively,
- humans can review receipts and diffs,
- merges happen only after gates.
Practical rule
If an agent can execute, it needs a sandbox. If it can ship, it needs two sandboxes.