Run a coding agent in a hardened, per-project container — on plain podman or docker, no hypervisor required.
A minimal, engine-agnostic sandbox for coding agents — per-project hardening, persistent state, host config sharing — built on ordinary podman/docker. No hypervisor, no host modifications. It runs the same anywhere podman or docker is installed.
⚠️ Alpha. This is early, actively-changing software. Not all entrypoints and flags have been manually tested yet — expect rough edges, and review the behavior yourself before relying on it.
- Per-project isolation. One sandbox per working directory, keyed off a hash of its path. An agent in one project can't reach another project's sandbox.
- Hardened by default. Non-root,
--cap-drop=ALL,no-new-privileges, read-only rootfs, memory/cpu/pid caps. See Security model. - Persistent state.
/home/agentsurvives container rebuilds, so agent config and history stick around. - Portable. One script, either engine, auto-detected.
- Approve once. Anything that can run host code or widen the sandbox — the build Containerfile, a non-loopback port — is gated behind an explicit flag.
podmanordockerbashpython33.11+ — only when a project ships an.agent-sandbox/config.toml(needed fortomllib). Projects without one need nothing extra.
git clone https://github.com/USER/agent-sandbox && cd agent-sandbox
podman build -t agent-sandbox:latest -f Containerfile .
chmod +x agent-sandbox
mkdir -p ~/.local/bin
ln -sf "$PWD/agent-sandbox" ~/.local/bin/agent-sandboxThen, in any project:
cd ~/src/some-project
agent-sandbox init # detect toolchain + harness, scaffold .agent-sandbox/
agent-sandbox # create (or resume) this project's sandbox, run `agent`Other common launches:
agent-sandbox --new # destroy + recreate the container (persisted home survives)
agent-sandbox -- bash # drop into a shell instead of running the agent
agent-sandbox --build # approve + build the project's .agent-sandbox/Containerfile
agent-sandbox name # print this project's container name (touches no engine)
agent-sandbox exec -- ls # run a command in the sandbox non-interactivelyname and exec are the supervisor channel: a script outside the sandbox can
resolve the container for a directory, then drive a tool inside it (tmux is in
the base image) with stdout, stderr and the exit code coming straight back.
init scans for marker files (go.mod, package.json, Cargo.toml, …),
pre-selects the matching tools, asks which agent harness to install, and
scaffolds a committed-plus-gitignored .agent-sandbox/ directory. Sandboxes are
keyed off a hash of the working directory, so re-running from the same project
always reconnects to the same container and its persisted /home/agent.
The full walkthrough — scaffolding, joining a project someone else set up, and the two things you approve once — is in Getting started.
| Guide | What's in it |
|---|---|
| Getting started | init, generated files, joining a shared project, the approval gates |
| Configuration | config.toml / config.local.toml, precedence, [env], env-var reference |
| Security model | what's hardened and how, gVisor, the host-engine escape hatch |
| Networking | per-engine isolation, egress allow-listing |
| Credentials | SSH agent forwarding, GitHub auth forwarding |
This gets you most of what a microVM sandbox promises — non-root, resource
limits, filesystem isolation — via ordinary container primitives, no hypervisor. It is
not as strong as a real microVM: a container escape is a different threat
model than a VM escape. For a stronger boundary without a hypervisor, point
AGENT_SANDBOX_RUNTIME at gVisor's runsc. The details, plus the deliberate
escape hatches (host engine socket, credential forwarding) and their tradeoffs,
are in Security model.
sudo dnf install -y bats # or: brew install bats-core
bats test/parse-config.bats test/launcher.bats test/recipes.bats test/init.batsThe launcher tests run against a fake engine on PATH, so they need neither
podman nor docker. The container smoke test is opt-in:
podman build -t agent-sandbox:latest -f Containerfile .
AGENT_SANDBOX_IT=1 bats test/integration.batsThis project was built with the help of AI coding assistants. Review the code and its security posture yourself before relying on it.
MIT © 2026 JP Tissot