Dev-sandbox – One bash script to isolate AI coding agents with Podman

Developer kosmrljt released dev-sandbox, a single bash script that isolates AI coding agents such as Claude Code and Google's Antigravity in Podman containers, optionally using krun microVMs for stronger isolation. The tool, tested on Fedora 44, mounts only the current project directory, hides host files like SSH keys and AWS credentials, and offers four profiles including a VNC GUI option. It addresses risks like prompt injection and malicious packages, though it does not prevent writes to .git/hooks or persistent volumes.

Run AI coding agents in isolated Podman containers, optionally with krun microVMs. For Linux distributions with Podman support. Developed and tested on Fedora 44. One self-contained bash script. No dependencies beyond Podman. Configure profiles, build, run — everything in a single file. AI coding agents need shell access and run arbitrary code. Without isolation: - An agent can read ~/.ssh/ , ~/.aws/ , browser cookies, API keys - A malicious pip package in setup.py can exfiltrate data silently - Prompt injection in a file can instruct the agent to run destructive commands - You have no visibility into what network connections the agent makes dev-sandbox runs each agent in its own isolated environment with only the current project directory visible. What this does not prevent: an agent can write to .git/hooks and persistent volumes, which execute on the next run. See docs/SECURITY.md /kosmrljt/dev-sandbox/blob/main/docs/SECURITY.md . Install Fedora/RHEL sudo dnf install podman crun-krun Install Ubuntu/Debian sudo apt install podman Download curl -o ~/.local/bin/dev-sandbox https://raw.githubusercontent.com/kosmrljt/dev-sandbox/main/dev-sandbox.sh chmod +x ~/.local/bin/dev-sandbox Run from your project directory only this directory is visible inside the sandbox cd ~/my-project dev-sandbox with krun Fedora dev-sandbox --no-krun without krun Ubuntu or any Linux The first run builds images ~1.6 GB, several minutes . Subsequent runs start in seconds. The default profile is configured for Claude Code — edit the script to change. Once inside, you are in an isolated container: claude /app/my-project-- HASH $ ← colored prompt shows profile name - You are user dev , not your host user - Only your project directory is visible mounted at /app/... - Your home directory, SSH keys, and other host files are not accessible - pip packages, credentials, and config persist between sessions in named volumes - Type exit to leave Four built-in profiles with color-coded prompts. Each is isolated — separate volumes, credentials, and settings. | Profile | Agent | Color | Description | |---|---|---|---| claude default | Claude Code | Green | | research | None template | Red | Add your own untrusted agents | agy | Antigravity | Yellow | Google AI agent | vncgui | GUI apps | Purple | VNC + XFCE desktop | dev-sandbox claude default claude start agent inside container dev-sandbox -p agy antigravity agy start agent inside container dev-sandbox -p research empty template, add your agents dev-sandbox -p vncgui XFCE desktop On host: connect with VNC viewer e.g. TigerVNC vncviewer localhost:5901 password: sandbox Show resolved settings for any profile: dev-sandbox info default profile dev-sandbox -p research info specific profile | Need | Runtime | |---|---| | VM isolation + firewall | krun, SSH off auto-passt | | VM isolation + SSH terminal | krun auto-TSI or --tsi | | VS Code Remote SSH | --no-krun | | Firewall + SSH | --no-krun | krun runs its own Linux kernel inside a microVM — a different isolation boundary than container namespaces. Standard container shares the host kernel but has full support for SSH tunneling and firewall. Default is krun. Architecture details: docs/ARCHITECTURE.md /kosmrljt/dev-sandbox/blob/main/docs/ARCHITECTURE.md . php graph LR Script dev-sandbox.sh -- |build| Image Profile Image Script -- |run| Container Container --- Volumes Named Volumes Project Project Dir -- |bind mount| Container All traffic through SOCKS proxy on host dev-sandbox --proxy 1080 No outbound traffic dev-sandbox --net locked SSH for VS Code requires --no-krun dev-sandbox --no-krun --ssh-port 2228 --ssh-key ~/.ssh/id ed25519.pub Pass env from host never in script or CLI history dev-sandbox --env ANTHROPIC API KEY Resource limits dev-sandbox --ram 8192 --cpus 8 All flags: dev-sandbox help Defaults apply to all profiles. Each profile only overrides what differs: DEFAULT USE KRUN=true DEFAULT SSH PORT=0 DEFAULT COLOR="0" 31=red, 32=green, 33=yellow PROFILE claude COLOR="32" Green — trusted PROFILE research COLOR="31" Red — untrusted PROFILE research SSH PORT=0 No SSH → passt → firewall works ALL PROFILES= claude research agy vncgui Adding a new profile: PROFILE test DESCRIPTION="My test sandbox" PROFILE test COLOR="33" ALL PROFILES= claude research agy vncgui test Settings resolve: CLI flag Profile Environment Default. Full configuration reference: docs/CONFIGURATION.md /kosmrljt/dev-sandbox/blob/main/docs/CONFIGURATION.md . Podman 4.x+ — sudo dnf install podman Fedora/RHEL , sudo apt install podman Ubuntu/Debian crun-krun — optional, for krun microVM mode. Without it, use --no-krun for standard containers passt — usually installed with crun-krun Optional: gocryptfs for encrypted directories, btrfs for quotas and snapshots. krun + SSH port mapping : Does not work with passt networking. The script uses passt when firewall is active or SSH is off, TSI otherwise. TSI connection bottleneck : TSI stalls under many concurrent connections e.g. loading a portal with many resources . This is why passt is preferred. Use --tsi only for testing. No : Use SSH or tmux for additional terminals. podman exec with krun: Bind-mounted project directory is writable. An agent can plant hooks that execute on the host. Review changes after sessions. .git/hooks tty warning : tty: ttyname error on krun startup is cosmetic. urllight https://github.com/kosmrljt/urllight — SOCKS5 proxy with live terminal dashboard. Route sandbox traffic through it to see every connection and DNS query. MIT © Tomaž Košmrlj Inspired by the Fedora Magazine article on sandboxing AI agents with microVMs https://fedoramagazine.org/sandbox-ai-coding-agents-with-microvms-on-fedora-linux/ . Built through iterative pair programming with Claude Anthropic .