chryaner/terrarium

**Real, disposable computers in seconds, for you and your AI agent.**
Fork a fresh Windows or Linux machine, use it, break it, reset it to spotless in
the time it takes to read this.
Get started
You need a Windows host with VirtualBox 7.x.
Do not have it yet?
With Claude Code
One command. npx fetches the package with the terrarium binary inside, so
there is nothing else to install:
Open a new Claude Code session and ask for a machine:
> Fork a fresh debian-12 machine, run uname -a in it, then delete it.
The agent checks the host, downloads the image, builds it, forks it, and
reports back. Linux images download themselves; a Windows machine needs an
installation ISO from you, once - see Images.
From the command line
Then:
ssh t1 opens a shell, rm t1 deletes the machine, down and start park
and wake it. fork --ttl 2h marks an env to expire and terrarium gc removes
the expired ones.
No Node? Install covers Scoop, Go, and other MCP clients.
Why
Containers are the right way to ship a Linux service and the wrong way to test a
whole **system**: every container borrows the host's kernel, so a build that
passes in one can still fail on real hardware. VMs have always fixed that. What
they lacked was the container workflow: image, run, throw away.
terrarium is that workflow on top of the VirtualBox you already have. Fork a
golden image in a tenth of a second. Wreck the fork and put it back in seconds.
Do it from the command line, or hand the same power to an AI agent over MCP. It
ships no virtualization code, wraps VBoxManage, and never touches a VM it did
not create.
What people use it for:
- **Set the goal, walk away.** Give an agent a real disposable machine over MCP
and a goal; it builds, fails, reverts, and retries on its own, unsupervised, all
the way to installing something end to end - and the task can involve the screen,
not just the command line.
- **Let an agent test an install end to end** on a real machine, from first boot
to a working app.
- **Let an agent write a guide or reproduce a bug** and hand back a step-by-step
screenshot trail or a GIF, exactly like the recordings in this README.
- **Isolated, disposable, real.** Do sensitive or risky work on a machine you can
throw away, so it never touches your own.
- **Clean-machine testing.** Run your installer or build on a machine that has
never seen your dev setup, and "works on my machine" stops being an argument.
Contents
- Get started
- Features
- Install
- How fast
- Images
- What it is not
Features
Every recording below is real: real commands, real screenshots read from the
guest's video memory, and a timer that shows real wall-clock seconds.
docs/demo explains how they are made.
**Fork Windows: a desktop from cold in ~40s**
**Fork Linux: SSH answering in ~20s**
**Brick it, then revert it: clean again in 13s**
**Claude wins Minesweeper on XP: no SSH, nothing installed**
How it compares
| | **terrarium** | Docker | VirtualBox | Vagrant | Hyper-V | Multipass | WSL2 |
| ---------------------------------------- | :-----------: | :----: | :--------: | :-----: | :-----: | :-------: | :--: |
| a real, whole machine (its own kernel) | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Windows guests | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| legacy guests (XP era) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| new machine in one command, seconds | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| reset to clean state in seconds | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| environment shared as a small text file | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| drives GUI-only guests (screen, mouse) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| AI agent tools built in (MCP) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| production workloads | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| runs on any host OS | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
If your work fits in a container, use Docker. When it needs a real, whole
machine you can break and un-break - and the last two rows are prices you can
pay - the first column is the point of this project. VirtualBox gets its own