terrarium

몇 초 만에 준비되는, 버려도 되는 실제 컴퓨터 - 당신과 당신의 AI 에이전트를 위해.

새 Windows 또는 Linux 머신을 포크하고, 사용하고, 망가뜨리고, 이 글을 읽는 데 걸리는 시간 안에 말끔한 상태로 리셋하세요.

왜

컨테이너는 Linux 서비스를 배포하는 올바른 방법이지만, 전체 시스템을 테스트하기에는 잘못된 방법입니다. 모든 컨테이너는 호스트의 커널을 빌려 쓰기 때문에, 한 컨테이너에서 통과한 빌드가 실제 하드웨어에서는 실패할 수 있습니다. VM은 항상 그 문제를 해결해 왔습니다. VM에 없던 것은 컨테이너의 워크플로, 즉 이미지 만들고, 실행하고, 버리기였습니다.

terrarium은 여러분이 이미 가지고 있는 VirtualBox 위에서 그 워크플로를 제공합니다. 골든 이미지를 0.1초 만에 포크하세요. 포크를 망가뜨렸다가 몇 초 만에 되돌릴 수 있습니다. 명령줄에서 실행하거나, MCP를 통해 AI 에이전트에게도 같은 능력을 넘겨줄 수 있습니다. 자체 가상화 코드는 포함하지 않고 VBoxManage를 감싸며, 자신이 만들지 않은 VM은 절대 건드리지 않습니다.

사람들이 사용하는 용도:

• 목표를 정하고 떠나세요. MCP를 통해 에이전트에게 실제 일회용 머신과 목표를 주면, 에이전트는 감독 없이 스스로 빌드하고, 실패하고, 되돌리고, 재시도하면서 무언가를 처음부터 끝까지 설치합니다. 작업은 명령줄뿐 아니라 화면을 다루는 일이 될 수도 있습니다.

• 에이전트가 실제 머신에서 설치를 처음부터 끝까지 테스트하게 하세요. 첫 부팅부터 앱이 동작할 때까지.

• 에이전트가 가이드를 작성하거나 버그를 재현하고, 이 README의 녹화 영상처럼 단계별 스크린샷 또는 GIF를 돌려주게 하세요.

• 격리되고, 일회용이며, 실제입니다. 민감하거나 위험한 작업을 버릴 수 있는 머신에서 수행하므로, 내 머신에는 절대 영향을 미치지 않습니다.

• 깨끗한 머신 테스트. 개발 환경을 한 번도 접하지 않은 머신에서 설치 프로그램이나 빌드를 실행해 보세요. "내 컴퓨터에서는 되는데"라는 변명은 더 이상 통하지 않습니다.

Related MCP server: wisp

목차

• 기능

• 설치

• 빠른 시작

• 얼마나 빠른가

• 이미지

• 이것이 아닌 것

기능

아래 모든 녹화는 실제입니다. 실제 명령, 게스트의 비디오 메모리에서 읽어낸 실제 스크린샷, 그리고 실제 경과 시간(벽시계 시간)을 보여주는 타이머입니다. docs/demo에서 어떻게 만들었는지 설명합니다.

Windows 포크: 콜드 스타트에서 데스크톱까지 ~40초

Linux 포크: SSH 응답까지 ~20초

벽돌로 만들었다가 되돌리기: 13초 만에 다시 깨끗하게

Claude가 XP에서 지뢰찾기 승리: SSH도, 설치된 것도 없음

비교

작업이 컨테이너에 맞다면 Docker를 사용하세요. 실제 완전한 머신이 필요하고, 그것을 망가뜨렸다가 되살릴 수 있어야 한다면 - 그리고 마지막 두 행이 지불할 수 있는 비용이라면 - 첫 번째 열이 이 프로젝트의 핵심입니다. VirtualBox가 의도적으로 별도 열을 차지하는 이유는, terrarium이 VirtualBox 위에서 실행되므로 그 열의 초록색 절반은 엔진이고, 빨간색 절반은 이 프로젝트가 추가하는 부분이기 때문입니다.

프로젝트별 개발 환경

# 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가 너무 오래된 OS를 다루는 방식입니다. 위의 지뢰찾기 녹화가 정확히 그 모습입니다. 연결 시 서버는 에이전트에게 먼저 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 호스트가 필요합니다(PATH에 VBoxManage). 그런 다음 머신이 준비되었는지 확인하세요:

$ 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)에서 측정했습니다. 수치는 다를 수 있지만 양상은 다르지 않을 것입니다. 포크는 연결 클론입니다. 골든의 디스크를 공유하기 때문에 클론 비용이 몇 분과 몇 GB가 아니라 0.1초와 몇 MB에 불과한 것입니다.

이미지

골든은 공급업체가 공식 배포하는 이미지에 몇 줄의 YAML을 더한 것입니다. 따라서 바이트는 항상 해당 배포판을 유지 관리하는 곳에서 나옵니다. 이미지를 추가하는 것은 파일 하나를 담은 풀 리퀘스트입니다.

Linux: 자동으로 다운로드

terrarium get <name>은 공식 클라우드 이미지를 다운로드하고, 생성된 SSH 키를 심고, 한 번 부팅한 다음 스냅샷을 만듭니다. 각각 약 1분이 걸립니다.

Windows: ISO 직접 준비

Windows 클라우드 이미지는 없고 Microsoft 미디어는 재배포할 수 없으므로, ISO를 한 번 다운로드하면 terrarium이 실제 설치 프로그램을 무인으로 실행합니다:

1. Microsoft에서 설치 ISO를 다운로드합니다.

2. 레시피 이름에 맞춰 %LOCALAPPDATA%\terrarium\isos\에 저장합니다: win10.iso, winxp.iso.

3. terrarium get win10을 실행합니다. 완전 무인 설치이며, win10은 약 10분, XP는 약 7분이 걸립니다.

win10과 winxp가 현재 제공됩니다. XP는 OpenSSH보다 오래된 OS이므로, XP 포크는 exec 대신 screenshot, click, type, keys로 제어합니다. 그리고 XP 레시피에는 로컬 오버라이드에서 직접 제공하는 제품 키가 필요합니다. 레시피 세부 사항, 프라이빗 미러, 무인 설치 내부 동작은 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. 레시피, 이슈, 현장 보고서를 환영합니다. 가장 유용한 기여는 사람들이 실제로 사용하는 이미지의 레시피입니다.