Run powerful development agents without handing them your whole machine.
Bunkerbox is an isolation layer for coding agents, CLIs, and other developer tools that need to work inside a project directory. Instead of running those tools directly on the host, Bunkerbox runs them inside a Kata-backed container with a controlled workspace, controlled home directory, and explicit runtime configuration.
It is built for the world where developer tools are becoming more capable, more autonomous, and more deeply integrated into local workflows. Those tools are useful, but they should not automatically inherit your full shell environment, your host home directory, your credentials, and your entire filesystem. Bunkerbox gives them a smaller box to work in.
A tool launched through Bunkerbox sees the project workspace it needs, but not the whole host. Its application state can be persisted between runs without exposing the real user home. Its image is built ahead of time from a reproducible config. Its runtime behavior is described separately, so packaging a tool is a matter of pairing an OCI image with a small runtime config.
When the agent runs a build command like cargo build, that command executes on your host — but not freely. Bunkerbox wraps it in a bubblewrap sandbox that strips the environment, blocks the network, and exposes only the tools and directories declared in a sandbox profile. The agent can compile your code. It cannot read your SSH keys, curl a payload, or peek at host processes.
The result is a workflow where tools still feel like normal commands, but run with a stronger boundary around them.
A packaged tool can be invoked like any other command:
opencodeBehind that command, Bunkerbox loads the matching runtime configuration, imports the prepared OCI image when needed, mounts the project workspace, prepares the tool home, applies network settings, and starts the tool inside a Kata container.
For development, the repository exposes the workflow through Makefile targets. Build an image from an image config:
make image IMAGE=images/opencode.confImport an OCI archive for local development:
make install-image OCI=bunkerbox-opencode-1.17.18.ociBuild the documentation website:
make docsThe generated documentation site is written to target/site-docs/.
Bunkerbox separates image building from runtime behavior. Image configs live in images/ and describe how a tool image is built. Runtime configs live in runtime/ and describe how that image should be executed: workspace mode, home persistence, network mode, and allowed destinations.
In a packaged install, a command such as opencode can be a symlink to the Bunkerbox binary. Bunkerbox uses the invoked command name to load the matching config from /usr/share/bunkerbox. That makes packaged tools feel ordinary while keeping the isolation behavior centralized.
Bunkerbox is a proof of concept. It is focused on exploring a safer local execution model for agentic developer tools using OCI images, containerd, and Kata Containers.
The full documentation is built as a static website:
make docsOpen the generated site from:
target/site-docs/
The project also includes Read the Docs configuration for public documentation hosting.