A container for safer vibecoding. Runs OpenCode v2 in a reusable podman container bound to your current directory.
An autonomous agent runs shell commands and edits files with your real credentials. A container bounds the blast radius:
- Filesystem scope. The agent sees only the bind-mounted workspace, not your whole home directory or other projects. Sensitive host paths (for example
~/.ssh,/proc, runtime dirs) are rejected. - Credential exposure is bounded. Legacy host auth is mounted read-only and imported into the container on first use; OpenCode v2 then keeps credentials in its container-local database. Private SSH keys are not mounted, and only specific API key env vars are forwarded at exec time. Network is enabled, so the agent can still exfiltrate what it can read.
sudowithout host-root privileges. Passwordless sudo inside the container maps to your unprivileged host user under rootless podman, not real root. Rootful podman is refused.- Git hooks and config are protected when present. For a normal repository root (
.gitdirectory), hooks/config and.git/modulesadmin paths stay read-only while index/objects/refs remain writable so the agent can stage and commit. Git is optional; non-git directories work. Linked worktrees and submodule checkouts used as the workspace root are unsupported for in-container Git. - Reversible. Throw away a bad state with
clankbox rm; the image is shared and rebuildable. - Pinned tools. Node.js and the NVIDIA keyring package use embedded versions and SHA-256 hashes. OpenCode v2 uses a pinned version and SHA-512 npm integrity hashes. Apt upgrades inside the container remain rolling.
A sandbox is a backstop, not a substitute for judgment. Agents ignore instructions, and workspace writes (Makefiles, scripts, CI configs) can execute on the host outside the container. Review changes before running them on the host. See Security details for the full picture.
- Python 3.10+
- podman in rootless mode
- network access to build the image and for tools inside the container
- Linux amd64 or arm64 (Node and OpenCode v2 pins cover these architectures)
Runs on Linux hosts, including Linux guests such as VMs and WSL2 distros (e.g. Ubuntu). On WSL2 or a VM, keep your project on the Linux filesystem (~/...) rather than a Windows mount (/mnt/c/...) for correct permissions and performance.
sudo apt install podman # Debian / Ubuntu / WSL
sudo dnf install podman # Fedora
podman run --rm hello-world
podman info --format '{{.Host.Security.Rootless}}' # should print trueThe launcher is self-contained (Dockerfile and pins are embedded). Copy it onto your PATH:
mkdir -p ~/.local/bin
install -m 0755 ./clankbox ~/.local/bin/clankbox
# ensure ~/.local/bin is on PATHDo not symlink the launcher into a project directory you will sandbox.
git pull
install -m 0755 ./clankbox ~/.local/bin/clankbox # refresh the installed copy
clankbox build # rebuild image if the base changed
# existing projects:
clankbox update # re-apply pinned Node/OpenCode v2
# or after schema changes:
clankbox rm && clankbox initcd /path/to/your/project
clankbox init # create and provision the container (once per project)
clankbox init --nvidia # same, plus GPU access and CUDA runtime libraries
clankbox init --x11 # same, plus host X11 display passthrough
clankbox opencode # start opencode
clankbox oc # same (alias for 'opencode')init builds the image if needed, creates the container, and installs the pinned
Node.js and OpenCode v2 versions embedded in the launcher.
Containers from older schema versions must be removed and re-created
(clankbox rm then clankbox init). rm accepts legacy schemas so that works.
Existing containers can be upgraded in place with clankbox update. On the first
OpenCode invocation, v2 migrates its data and imports supported credentials from
the staged legacy auth.json into its SQLite database. That database, including
credentials, persists in the container. Host auth changes are not synced after
this one-time import; manage credentials with clankbox opencode auth login.
clankbox rm removes the container database and its credentials.
Clankbox runs the TUI and supported server-backed commands in standalone mode by default, so each invocation receives the current forwarded API-key environment. OpenCode data remains persistent between invocations. A system-level setting disables OpenCode self-updates so the launcher pin stays authoritative.
init --nvidia needs host NVIDIA driver and nvidia-container-toolkit
with CDI. init --x11 needs host DISPLAY and uses host networking for SSH -Y.
clankbox list
clankbox df
clankbox stop
clankbox stop --all
clankbox rm
clankbox rm clankbox-0123456789ab # sandbox ID from clankbox list
clankbox rm --all
clankbox build
clankbox update
clankbox update --all
clankbox opencode --continue
clankbox oc run "explain this repo"clankbox rm <sandbox-id> removes one sandbox by the name shown in the NAMES
column of clankbox list. With no ID, rm still targets the current directory.
Advisory locks in ~/.local/state/clankbox/locks (or $XDG_STATE_HOME/clankbox/locks)
serialize image builds and container lifecycle. Sessions can run concurrently after
podman exec. stop and rm can end active sessions by design.
Debian bookworm slim (digest-pinned) plus: git, curl, wget, jq, ripgrep, python3, make/g++, openssh-client, zip/unzip, sudo.
Node.js and OpenCode v2 are provisioned at init/update from pins in the
launcher. python3 -B bump-pins.py opencode checks for a stable v2 update;
python3 -B bump-pins.py --bump opencode updates the launcher pin. Reinstall the
launcher and run clankbox update (and clankbox build if the base image changed).
The clank user has passwordless sudo inside the container. Under rootless
podman this is isolated from host root. Packages persist until clankbox rm.
python3 -B tests/test_clankbox.pySee Design and Security details.
