Getting Started

Requirements

macOS 26+ (Tahoe or later)
Apple’s container CLI: brew install container
Swift 6.3+ (only for building from source; make test prefers Xcode when installed)

Installing

Homebrew (recommended)

brew install vmunix/tap/spawn

From source

git clone https://github.com/vmunix/spawn.git
cd spawn
make install    # builds release and installs to ~/.local/bin

Add ~/.local/bin to your PATH if it isn’t already:

export PATH="$HOME/.local/bin:$PATH"

Add that line to your shell profile (~/.zshrc or ~/.bashrc) to make it permanent.

Building container images

spawn uses layered container images. The base image must be built first, then toolchain-specific images extend it.

# Build all images at once (base is built first automatically)
spawn build

# Or build individually
spawn build base
spawn build rust
spawn build cpp
spawn build go
spawn build js

The builder container defaults to 4 CPUs and 8GB memory. If a build fails with an out-of-memory error, increase the allocation:

spawn build --memory 16g --cpus 8

First run

Navigate to a project directory and run spawn:

cd ~/code/my-project
spawn .

spawn will:

Detect your project’s toolchain from files like Cargo.toml, go.mod, CMakeLists.txt, package.json, bun.lock, or deno.json
Select the matching container image (e.g., spawn-rust:latest)
Mount your project directory read/write into the container
Copy your git config and SSH keys into the container
Launch Claude Code in safe mode

On first run, Claude Code will prompt you to authenticate via OAuth. Your credentials are persisted in ~/.local/state/spawn/claude-code/ so you only need to authenticate once.

To use Codex instead:

spawn . codex

To skip all permission prompts:

spawn . --yolo

To drop into a bash shell inside the container (useful for debugging):

spawn . --shell

If your project already has a .devcontainer/devcontainer.json, spawn uses that as an explicit signal before falling back to file-based heuristics. This makes existing VS Code devcontainer projects work nicely with spawn.