terrarium

真实、可抛弃的计算机，数秒即可获得，供你和你的 AI 代理使用。

克隆一台全新的 Windows 或 Linux 机器，使用它、弄坏它，然后在读完这句话的时间内把它恢复得一尘不染。

为什么

容器是交付 Linux 服务的正确方式，但却是测试整个系统的错误方式：每个容器都借用宿主机的内核，因此在一个容器中通过的构建仍可能在真实硬件上失败。虚拟机一直能解决这个问题。它们所缺少的是容器的工作流：镜像、运行、丢弃。

terrarium 将这一工作流构建在你已有的 VirtualBox 之上。十分之一秒内克隆一个黄金镜像。弄坏克隆体，然后在几秒内恢复。从命令行操作，或通过 MCP 将同样的能力交给 AI 代理。它不附带任何虚拟化代码，只是封装 VBoxManage，并且从不触碰它未创建的虚拟机。

人们用它来做什么：

• 设定目标，然后走开。 通过 MCP 给代理一台真实、可抛弃的机器和一个目标；它会自行构建、失败、回滚、重试，全程无需监督，直到端到端地安装好某个东西——而且任务可以涉及屏幕，而不仅仅是命令行。

• 让代理在真实机器上端到端测试安装，从首次启动到应用可用。

• 让代理编写指南或复现 bug，并交回一步步的截图轨迹或 GIF，就像本 README 中的录制一样。

• 隔离、可抛弃、真实。 在一台可以丢弃的机器上做敏感或高风险的工作，这样它永远不会触及你自己的机器。

• 干净机器测试。 在一台从未接触过你的开发环境的机器上运行安装程序或构建，这样“在我机器上能跑”就不再是借口。

Related MCP server: wisp

目录

• 功能

• 安装

• 快速开始

• 速度如何

• 镜像

• 它不是什么

功能

下面的每段录制都是真实的：真实的命令、从客户机视频内存中读取的真实截图，以及显示真实挂钟秒数的计时器。docs/demo 说明了它们的制作方法。

克隆 Windows：冷启动到桌面 ~40s

克隆 Linux：SSH 响应 ~20s

变砖，然后恢复：13 秒内恢复干净

Claude 在 XP 上通关 Minesweeper：无需 SSH，无需安装任何东西

对比

如果你的工作适合放在容器里，就用 Docker。当它需要一台可以弄坏再修好的真实、完整的机器时——而且最后两行是你愿意付出的代价——第一列就是这个项目的意义所在。VirtualBox 特意拥有自己的一列：terrarium 运行在它之上，所以那一列的绿色部分是引擎，红色部分是这个项目新增的内容。

每个项目一个开发环境

# terrarium.yaml, committed in your repo
image: ubuntu-24.04
cpus: 4
memory: 4096

terrarium up 会克隆一个以项目命名的环境，将项目文件夹共享到客户机的 /work，并将其添加到 ~/.ssh/config，因此 ssh <project> 可以工作，VS Code Remote-SSH 也能一键看到它。down 将其停驻，up 将其唤醒，revert 将其重置。

你的 AI 代理获得真实计算机

$ claude mcp add terrarium -- terrarium mcp

同一个二进制文件也是一个 MCP 服务器：上面的每条命令都是一个工具，此外还有 screenshot、click、scroll、type 和 keys——通过虚拟机管理程序注入屏幕、鼠标和键盘，因此无需在客户机中安装任何东西，也无需网络或增强功能。这就是代理驱动安装程序、登录屏幕或太老而无法使用 SSH 的操作系统的方式——正是上面 Minesweeper 录制所展示的。连接时，服务器会告诉代理先运行 doctor，并报告缺少了什么，而不是盲目乱试。

• 克隆一个干净的环境，在其中构建项目，告诉我 README 遗漏了什么。

• 在 Windows 环境中安装我们的应用，并逐步截图。

对于启用了 SSH 的 Windows 客户机，terrarium rdp 会打开一个已登录的完整桌面。

安装

$ scoop bucket add terrarium https://github.com/chryaner/terrarium
$ scoop install terrarium

或者，在 Go >= 1.25 的情况下，运行 go install github.com/chryaner/terrarium/cmd/terrarium@latest，或在克隆的仓库中运行 go build -o terrarium ./cmd/terrarium。

需要一台装有 VirtualBox 7.x 的 Windows 主机（VBoxManage 在 PATH 中）。然后检查机器是否就绪：

$ terrarium doctor

Linux 镜像会自动下载。Windows 镜像则由你提供的安装 ISO 构建——有关放置位置和原因，请参阅 镜像。

快速开始

$ terrarium get debian-12          # build a golden: download, boot, snapshot (~40s)
$ terrarium fork debian-12 t1      # a throwaway machine, SSH-ready in ~20s
$ terrarium exec t1 -- uname -a
$ terrarium ssh t1
$ terrarium revert t1              # back to clean in seconds
$ terrarium rm t1

down 和 start 可以停驻和唤醒环境而不丢失它。fork --ttl 2h 将环境标记为过期，terrarium gc 会移除已过期的环境（以及你手动删除其 VM 的任何环境）。

速度如何

在一台台式机（i9-14900K、NVMe、VirtualBox 7.2）上测得。你的数字会不同；但趋势不会。克隆体是链接克隆：它们共享黄金镜像的磁盘，这就是为什么克隆只需十分之一秒和几 MB，而不是几分钟和几 GB。

镜像

黄金镜像是供应商自己发布的镜像加上几行 YAML，因此字节始终来自维护它们的发行版。添加一个镜像就是一个包含一个文件的拉取请求。

Linux：为你自动下载

terrarium get <name> 会下载官方云镜像，用生成的 SSH 密钥为其播种，启动一次，然后拍摄快照。每个大约一分钟。

Windows：自带 ISO

没有 Windows 云镜像，而且 Microsoft 的介质不能重新分发，所以你只需下载一次 ISO，terrarium 会无人值守地运行真正的安装程序：

1. 从 Microsoft 下载安装 ISO。

2. 将其保存在 %LOCALAPPDATA%\terrarium\isos\ 中，并按配方命名：win10.iso、winxp.iso。

3. 运行 terrarium get win10。完全无人值守：win10 大约十分钟，XP 七分钟。

win10 和 winxp 目前随附。XP 早于 OpenSSH，因此它的克隆体通过 screenshot、click、type 和 keys 来驱动，而不是 exec，而且它的配方需要你在本地覆盖中提供的产品密钥。配方细节、私有镜像和无人值守安装的内部机制见 docs/DESIGN.md。

叠加你自己的镜像

配方可以基于另一个镜像而不是介质来构建：from 指定基础镜像，setup 在其克隆体中运行命令，然后将结果扁平化为新的黄金镜像。YAML 文件是可共享的产物——拥有同一文件的队友可以从他们自己的基础镜像构建出等价的机器，因此无需交换任何磁盘镜像（也无需交换 Windows 许可证）。

# %LOCALAPPDATA%\terrarium\recipes\team-dev.yaml
name: team-dev
from: debian-12
setup:
  - sudo apt-get update
  - sudo apt-get install -y git build-essential

terrarium get team-dev 会在现有基础之上于数秒内构建它。对于你手动而非通过脚本创建的状态，terrarium promote <env> <name> 会直接将配置好的环境扁平化为黄金镜像。terrarium rm --golden <name> 会移除你不再需要的镜像。

它不是什么

• 尚不支持跨平台。 主机必须是装有 VirtualBox 的 Windows。按照设计，所有虚拟机管理程序调用都位于一个包之后，因此 QEMU 或 Hyper-V 驱动是一个计划中的入口，而不是一个承诺。

• 不用于生产。 克隆体是开发和测试用的可抛弃资源。

• 不是密钥管理器。 Windows 黄金镜像的密码以纯文本形式存储在本地，并且在安装过程中会短暂出现在 VBoxManage 命令行上。请使用一次性密码。

许可证

Apache-2.0。欢迎提供配方、问题和现场报告，最有用的贡献是提供一个人们实际使用的镜像配方。