ClodPod - Run AI agents in a macOS VM sandbox

Key features

• Builds a virtual machine and launches AI agents with access to your projects
• Enables mapping multiple projects in the same virtual machine simultaneously
• Open multiple AI agents sessions and shell prompts, or use the GUI
• Headless mode for CI/CD workflows with --no-graphics
• Includes Xcode and common development tools; you can add your own tools too
• Fast rebuild and relaunch using a three-layer APFS CoW caching system
• Named VM instances for switching between projects or worktree branches
• Parallel VM execution with configurable memory budget

Usage:

# Clone clodpod
git clone https://github.com/webcoyote/clodpod ~/projects/clodpod

# Create an alias for clod or add it to your path
alias clod="$HOME/projects/clodpod/clod"
# - or -
alias clod="$HOME/projects/clodpod/clod --no-graphics"
# - or -
PATH="$PATH:"$HOME/projects/clodpod"

# Note: for the first run you'll want to start in the project directory,
# which will get remembered. Use add/remove for changing projects.
cd "YOUR PROJECT DIRECTORY"

# Run Claude Code
clod claude
# also clod cl"

# Run OpenAI Codex
clod codex
# also "clod co"

# Run Google Gemini
clod gemini
# also "clod g"

# Or a command shell
clod shell
# also "clod s"

# Start virtual machine (useful for utilizing Virtual Machine GUI apps)
clod start

# Enable passwordless sudo in VM
ALLOW_SUDO=true clod build-base

# Disable passwordless sudo in VM (default)
ALLOW_SUDO=false clod build-base

# Stop all clodpod virtual machines
clod stop

# Add/remove/list projects
clod add "THIRD PROJECT DIRECTORY"          # also "clod a ..."
clod remove "FOURTH PROJECT DIRECTORY"      # also "clod rm ..."
clod list                                   # also "clod l", "clod ls"

Named VM instances

Create named VMs to keep separate environments for different projects or worktree branches. Each is a cheap APFS CoW clone of the base VM.

# Create a named VM with mounted directories
clod create myproject --dir project:/path/to/project
clod create feature-a --dir work:/path/to/repo/.worktrees/feature-a

# SSH into a named VM
clod shell myproject

# Multiple VMs can run simultaneously if memory budget allows
clod shell feature-a    # starts alongside myproject

# List named VMs
clod list

# Add or replace a mount on an existing instance
clod set --dir data:/Volumes/data myproject

# Remove a mount
clod set --dir-remove data myproject

# Clean up
clod destroy myproject
clod destroy --all

Memory budget

By default, VMs share a memory budget of 5/8 of host RAM. You can configure per-instance RAM and the total budget:

# Set RAM for a specific instance (takes effect on next launch)
clod set --ram 8G myproject

# Set workspace memory budget
clod set --max-memory 16G

# Create with specific RAM
clod create dev --ram 10G --dir project:/path

# Override RAM for one session
clod shell --ram 6G dev

# Split budget across multiple VMs (default: 1)
clod set --vm-count 2

# Reset to dynamic (use remaining budget)
clod set --ram default dev
clod set --max-memory default
clod set --vm-count default

Port forwarding

Forward host ports into the VM via SSH reverse tunnels so VM agents can reach host resources such as databases and local LLMs.

clod --forward-port 8080 --forward-port 3000 claude
CLOD_FORWARD_PORTS=8080,3000 clod shell dev    # env var alternative

Both methods can be combined.

macOS versions

By default ClodPod uses the ghcr.io/cirruslabs/macos-tahoe-xcode:latest VM flavor, but this is configurable by setting the MACOS_VERSION and MACOS_FLAVOR environment variables when building the VM:

MACOS_VERSION=sequoia MACOS_FLAVOR=vanilla clod shell

See the cirrus packages page on Github to see the available alternatives.

Setup notes

By default the guest CPU count is set to be identical to the host system, and guest memory to 5/8 * host memory (NOTE1) to provide resources for compiling projects in Xcode.

NOTE1: This value was empirically calculated (N=1) to leave plenty of memory for web-browsing, which I shouldn't be doing anyway.

Optional virtual machine configuration (example):

tart set clodpod-xcode --cpu 8
tart set clodpod-xcode --memory "$(( $(sysctl -n hw.memsize) * 2 / 3 / 1024 / 1024 ))"

Add your own tools and configuration

To add custom configuration; see ./guest/home/README.md.

Per-project Homebrew dependencies (Brewfile)

If a mounted project contains a Brewfile at its root, ClodPod will reconcile it via brew bundle automatically:

• At instance creation (clod create): every mounted project's Brewfile is applied.
• At every shell entry (clod claude, clod shell, etc.): the active project's Brewfile is checked with brew bundle check; install only runs on drift, so steady-state cost is negligible.

The default file is ./Brewfile; override per-session by setting the standard HOMEBREW_BUNDLE_FILE env var. Install uses --no-upgrade, so pinned versions stay pinned. Failures emit a loud warning but never block the VM or shell from starting. ClodPod does not run brew bundle cleanup — removal stays a manual call.

Background

This project exists because I was foolishly trying to find a way to insulate my computer from destruction by rogue AI agents when running (e.g.) Claude Code with --dangerously-skip-permissions (to avoid frequent "do you want to proceed?" dialogs), when perhaps I should have simply learned to accept their infrequent rages.

I experimented with running AI agents inside docker and podman containers (i.e. in Linux), but as my goal ultimate is to build apps using Xcode, I wanted to stick with OSX.

I considered using xtool, but instead went down a different rabbit hole and tried providing the containers with limited access from the guest OS to my host computer using GNU Rush (Remote User SHell). This worked but was limiting.

I then tried limiting filesystem access using exec-sandbox, and it works in a "proof-of-concept" sort of way, but the attack surface area was too large. I expect I'll come back to this because sandboxing is quite interesting all by itself.

Eventually I settled on running the whole thing inside a virtual machine, which is probably where I should have started.

In any event, this project is the result. Hope you like it.

Alternatives

• SandVault runs AI agents in a limited user account on macOS.
• Chamber is a proof-of-concept app for running Claude Code inside a macOS virtual machine.
• Claude Code Sandbox runs Claude Code in a Docker container (Linux)

License

Apache License, Version 2.0

ClodPod Copyright © 2025 Patrick Wyatt

See LICENSE.md for details.

Contributors

We welcome contributions and bug reports.

See CONTRIBUTORS.md for the list of contributors to this project.

Thanks to

This project builds on the great works of other open-source authors:

• Tart: macOS and Linux VMs on Apple Silicon (licensed under FSL-1.1-MIT; free for individuals, commercial use may require a paid license)
• Homebrew: 🍺 The missing package manager for macOS (or Linux)
• Sqlite: The most used database engine in the world
• Shellcheck: finds bugs in your shell scripts
• uv: An extremely fast Python package and project manager, written in Rust
• Claude Code Hooks Mastery: Quickly master how to use Claude Code hooks to add deterministic (or non-deterministic) control over Claude Code's behavior
• StatusLine: project status information for Claude Code

... as well as GNU, BSD, Linux, Git, Sqlite, Node, Python, netcat, jq, and more. "We stand upon the shoulders of giants."