dev-sandbox

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.

Why

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.

Quick start

# Prerequisites (Fedora/RHEL)
sudo dnf install podman crun-krun

# Prerequisites (Ubuntu/Debian)
sudo apt install podman crun

# Install
curl -o ~/.local/bin/dev-sandbox https://raw.githubusercontent.com/kosmrljt/dev-sandbox/dev-1.1.3/dev-sandbox.sh
chmod +x ~/.local/bin/dev-sandbox

# Optionally install new profiles
mkdir -p ~/.dev-sandbox
curl -L https://github.com/kosmrljt/dev-sandbox/archive/dev-1.1.3.tar.gz \
  | tar xz -C ~/.dev-sandbox --strip-components=2 dev-sandbox-dev-1.1.3/configs

# Run from your project directory
cd ~/my-project
dev-sandbox                      # with krun (Fedora)
dev-sandbox --no-krun            # without krun (Ubuntu or any Linux)

First run: Builds the container image (~1.4 GB, takes a few minutes).
Subsequent runs: Starts in (mili)seconds. Agent setup and logins are preserved across sessions.

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

Note (2026-10-25): After a recent Fedora update, krun's passt networking broke
(start passt error) due to a crun-krun ↔ passt version mismatch. Workaround: sudo dnf downgrade passt — or run with --tsi.

Test if the package update resolves the issue: podman run --rm --annotation run.oci.handler=krun --annotation krun.use_passt=1 fedora:44 echo ok

Profiles

Four built-in profiles with color-coded prompts. Each is isolated — separate volumes, credentials, and settings.

dev-sandbox                         # claude (default)
claude                              # start agent inside container

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

Usage examples

# 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

Requirements

• Podman 4.x+
• crun-krun — optional, for krun microVM mode. Without it, use --no-krun for standard containers
• passt — usually installed with crun-krun

If running dev-sandbox from a gocryptfs-mounted directory, mount with -allow_other and enable user_allow_other in /etc/fuse.conf. Otherwise Podman's user namespace cannot access the FUSE mount.

Choosing a runtime

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.

Architecture details: docs/ARCHITECTURE.md.

graph LR
    Script[dev-sandbox.sh] -->|build| Image[Profile Image]
    Script -->|run| Container
    Container --- Volumes[Named Volumes]
    Project[Project Dir] -->|bind mount| Container

Configuration

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.

External config files

Instead of editing the script, profiles and policies can be kept in separate config files loaded with --config. Config files can define new profiles (e.g. hardware development with USB and Wayland access) or modify existing ones (e.g. restricting git commands like push, tag, and branch creation). Multiple configs are composable:

dev-sandbox --config devhw.sh                          # new profile
dev-sandbox --config _git-guard.sh                     # policy for all profiles
dev-sandbox --config devhw.sh --config _git-guard.sh   # combine both

Config files are loaded from the current directory or ~/.dev-sandbox/. Install the included examples:

mkdir -p ~/.dev-sandbox
curl -sL https://github.com/kosmrljt/dev-sandbox/archive/refs/heads/main.tar.gz \
  | tar -xz -C ~/.dev-sandbox --strip-components=2 dev-sandbox-main/configs

Full configuration reference: docs/CONFIGURATION.md.

Known limitations

• Workspace Security: An agent can write to .git/hooks and persistent volumes, which execute on the next run. See docs/SECURITY.md.
• 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 podman exec with krun: Use SSH or tmux for additional terminals.
• tty warning: tty: ttyname error on krun startup is cosmetic.

Related

sockLight — SOCKS5 proxy with live terminal dashboard. Route sandbox traffic through it to see every connection and DNS query.

Documentation

• Architecture — how dev-sandbox works (images, volumes, networking, krun vs standard containers)
• Configuration — all profile variables, priority chain, persistence, CLI reference
• Security model — isolation boundaries, known limitations, sudo password handling, network modes
• Testing guide — step-by-step tests for all features, can be also a practical tutorial
• Bash tricks — patterns and gotchas discovered while building the script

License

MIT © Tomaž Košmrlj

Inspired by the Fedora Magazine article on sandboxing AI agents with microVMs. Built through iterative pair programming with Claude (Anthropic).