Skip to content
j33433Public

About

A container for safer opencode vibecoding

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

67 Commits

Folders and files

Repository files navigation

clankbox

clankbox logo

A container for safer vibecoding. Runs OpenCode v2 in a reusable podman container bound to your current directory.

Why run opencode in a container?

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.
  • sudo without 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 (.git directory), hooks/config and .git/modules admin 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.

Requirements

  • 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)

Platforms

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.

Setting up podman

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 true

Install

The 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 PATH

Do not symlink the launcher into a project directory you will sandbox.

Updating clankbox itself

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 init

Usage

cd /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.

OpenCode v2 migration

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.

Concurrent terminals

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.

Image contents

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.

Tests

python3 -B tests/test_clankbox.py

See Design and Security details.

About

A container for safer opencode vibecoding

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages