Lightweight, isolated microVMs for autonomous AI coding agents
Run AI coding agents 24/7 in isolated Firecracker VMs. Each project gets its own VM with full context, multi-repo support, and autonomous operation.
- 🤖 Autonomous - supports
ralph-claude-codeandralph-orchestrator - 🔒 Isolated - Dedicated VM per project, zero host pollution
- 🚀 Concurrent - Run unlimited VMs simultaneously
- 📚 Rich Context - Company docs, standards, architecture included
- 🔄 Multi-Repo - Agents work across multiple repositories
- 🎯 Simple CLI - Host commands abstract VM complexity
# Install
git clone https://github.com/user/agent-foundry.git
cd agent-foundry
./install.sh --prefix ~/.local
# Setup
foundry host setup
foundry template build base
foundry template build golden
# Create and run
foundry vm create my-project --project example-project
foundry agent start my-project ralph
foundry agent logs my-project --followAgent Foundry supports two autonomous Ralph integrations:
ralph(backed byfrankbria/ralph-claude-code)ralph-orchestrator(backed bymikeyobrien/ralph-orchestrator)
Each VM image should include exactly one Ralph variant. Configure template builds with:
# ~/.config/foundry/config.conf
RALPH_AGENT_VARIANT=ralph-claude-code
# or
RALPH_AGENT_VARIANT=ralph-orchestratorProject examples:
projects/example-project/(ralph-claude-code)projects/example-project-orchestrator/(ralph-orchestrator)
Host System (Arch/NixOS)
↓ Foundry CLI
↓ Firecracker + TAP (172.16.0.0/24)
↓
┌─────────┬─────────┬─────────┐
│ VM 1 │ VM 2 │ VM 3 │
│ .11 │ .12 │ .13 │
│ /root/ │ /root/ │ /root/ │
│ ├repos │ ├repos │ ├repos │
│ └.ralph│ └.ralph│ └.ralph│
│ Ralph → │ Gemini │ Codex │
│ Claude │ CLI │ CLI │
└─────────┴─────────┴─────────┘
- Autonomous Features: Define in
PROMPT.md, agent implements across repos - 24/7 Work: Start agent on refactoring, review progress in morning
- Parallel Development: Run 3-5 VMs on different projects simultaneously
- Team Collaboration: Share base templates with company standards
ralph-claude-code projects typically use this layout:
/root/ # VM workspace
├── .ralphrc # Config (optional, overrides default)
├── .ralph/ # Ralph files
│ ├── PROMPT.md # Mission: what to do
│ ├── fix_plan.md # Tasks: - [ ] checklist
│ ├── AGENT.md # Commands: npm test, etc
│ ├── specs/ # Requirements (optional)
│ └── logs/ # Execution logs
└── repos/ # Your code
├── backend/
└── frontend/
How it works:
- Ralph reads
PROMPT.md→ Understands mission - Reads
fix_plan.md→ Gets next task - Reads
AGENT.md→ Knows how to test - Makes changes → Runs tests → Checks off task
- Repeats until all done
For ralph-orchestrator, use top-level ralph.yml and PROMPT.md (see projects/example-project-orchestrator/).
Default (templates/.ralphrc.template) - Full tool access, used when no project config exists
Project-Specific (projects/your-project/.ralphrc) - Overrides default
Customize: ALLOWED_TOOLS, MAX_CALLS_PER_HOUR, CLAUDE_TIMEOUT_MINUTES, circuit breaker thresholds
# Customize for a project
cp templates/.ralphrc.template projects/my-project/.ralphrc
vim projects/my-project/.ralphrc
foundry workspace sync my-vm my-project # Apply to VMDefaults: 4 vCPUs, 8GB RAM, 20GB disk
Override:
- Global:
~/.config/foundry/config.conf - At create time: choose a different template and per-VM SSH key
Per-VM keypair in ~/.local/share/foundry/vms/<name>/ssh/. Never reads ~/.ssh/ unless you pass --ssh-key <path>.
Add to ~/.config/foundry/packages.txt:
postgresql
redis
go
rustup# VM lifecycle
foundry vm create <name> [template] [--project <project>] [--ssh-key <path>]
foundry vm start <name>
foundry vm stop <name>
foundry vm ssh <name> [command]
foundry vm destroy <name>
foundry vm list
foundry vm status <name>
foundry vm update <name>
# VM operations
foundry vm copy <src> <dst>
foundry vm rename <old> <new>
foundry vm snapshot <name> <snapshot>
# Agent management
foundry agent start <vm> <agent-type> # ralph, ralph-orchestrator, claude, gemini, codex
foundry agent stop <vm>
foundry agent restart <vm>
foundry agent logs <vm> [--follow]
foundry agent attach <vm>
foundry agent status <vm>
foundry agent gh-watcher <action> <vm>
# Workspace
foundry workspace init <vm> <config.json>
foundry workspace sync <vm> [project]
foundry workspace init-ralph <vm>
foundry workspace edit <vm> <file>
foundry workspace info <vm>
foundry workspace template [file]
# Templates
foundry template build base # Downloads Ubuntu 22.04 base
foundry template build golden # Configures AI tools (apt based)
foundry template list
# Host setup
foundry host setup
foundry host status
# Network
foundry network init
foundry network status
foundry network cleanupFull reference: CLI-REFERENCE.md
Host System:
- Linux (Arch, NixOS, Ubuntu, Fedora)
- KVM enabled (hardware virtualization)
- 4+ CPU cores, 16GB+ RAM recommended
- 100GB+ disk space
Dependencies:
- Firecracker, QEMU utils (
qemu-img), iproute2 (ip), iptables/nftables, jq, SSH, Git
NixOS: Use included shell.nix
- VISION.md - Project goals and philosophy
- ARCHITECTURE.md - Complete architecture overview
- CLI-REFERENCE.md - Full command reference
- RALPH-INTEGRATION.md - Ralph integration details
- TODO.md - Implementation roadmap
# For NixOS
nix-shell
# Run tests
# (tests are not fully scaffolded yet)
# Build templates
./scripts/build-ubuntu-base.shRelease bundle is built automatically by install.sh if needed.
🚧 Early Development - Core architecture defined, implementation in progress.
See TODO.md for roadmap.
MIT License - See LICENSE
- Read VISION.md and ARCHITECTURE.md
- Check TODO.md for open tasks
- Create issue or PR
- Follow existing code style
Built on Firecracker • Supports ralph-claude-code and ralph-orchestrator • Inspired by the Ralph Wiggum technique
- GitHub Issues: Report bugs, request features
- Discussions: Ask questions, share setups
- Wiki: Community guides and tips
Note: Agent Foundry is for development use only. Not intended for production workload hosting.