disposable VirtualBox VMs from the CLI or over MCP, for you and your AI agent
Terrarium has 24 well-named tools with comprehensive descriptions (avg 180 chars, within baseline 194). All tools have input schemas with typed parameters and descriptions. Naming follows verb_noun convention (env_fork, golden_get, env_exec). However, output schemas are not documented in the visible code, only input schemas are defined. Error handling is minimal; tools return raw errors without recovery guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels. Parameter descriptions are good but lack format constraints (e.g., no regex for 'name' fields, no min/max for numeric params). Missing pagination on list tools.
Check that this machine can run terrarium at all: VirtualBox present and responding, state directory writable, SSH client available. Call this once before anything else. Cheap and safe to call at any time. If it reports ok:false, report the failing check and its fix to the user rather than working around it.
Click the guest's screen at a position.
Create a blank environment with an installation ISO in its DVD drive and boot it, for an OS that has no recipe and no unattended installer - an old distribution, or one whose installer has to be answered by hand. The boot order is disk first, DVD second, so the installer runs while the disk is blank and the installed system boots itself afterwards. The result has no golden image and therefore no credentials: env_exec will not work on it. Drive the installer with env_screenshot, env_type, env_keys and env_click, and note that env_revert puts the blank disk back and restarts the install. When the OS is up, env_promote turns it into a golden - and golden_adopt then records the account created inside it. iso_path is a path on this host, where the server runs.
Shut an environment down, keeping its disk and state.
Run a shell command inside an environment and return its exit code and output. The command is one shell string: pipes, redirects, globs and quoting are interpreted by the guest shell, unlike the CLI's `terrarium exec`, which passes its arguments literally. Which shell that is: /bin/sh on Linux guests; on a Windows guest, the shell recorded for its golden, which is PowerShell for a golden terrarium built and cmd.exe for an older or adopted one, unless `terrarium adopt --shell` said otherwise. Pass shell (powershell, cmd or sh) to run under a different one, and script instead of command for anything multi-line or heavily quoted - a script reaches the shell on stdin, so nothing in it is re-parsed on the way. The environment must be running. Commands run as a user with passwordless sudo, so this can change the system.
Output schemas not documented. Tool descriptions explain what is returned (e.g., 'returns exit code and output'), but no formal output schema is visible in the code. LLMs cannot plan downstream tool calls without knowing response structure.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools are marked with Risk levels (READ_ONLY, WRITE, DESTRUCTIVE, REVERSIBLE) in comments, but these are not exposed as MCP tool annotations. Agents cannot distinguish safe from dangerous operations without parsing descriptions.
Numeric parameters lack min/max constraints. CPUs, memory_mb, disk_gb, timeout_sec, and coordinate parameters (x, y, clicks) have no documented bounds. LLMs can pass absurd values (e.g., 999999 CPUs, negative coordinates) that fail at runtime.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
Create a new environment from a golden image and boot it. Takes under a minute and costs tens of MB of disk. The environment is disposable: anything done inside it is lost on env_rm, and env_revert rewinds it to the state it had right after this call. If the golden has no SSH credentials recorded - env_list shows an empty ssh_user, which is normal for an old or GUI-only system - env_exec will not work on the result. Drive it with env_screenshot, env_type, env_keys and env_click instead.
Remove expired environments and unused golden images.
Press keys in the guest's keyboard.
List the golden images available to fork from and the environments that exist, with their SSH ports and whether each is currently running. Read-only.
Turn an environment into a golden image that other environments can be forked from.
Copy a file or directory out of an environment onto this host, over the same connection env_exec uses. guest_path is inside the guest and always uses forward slashes, Windows guests included; local_path is on the host, where this server runs, and its missing parent directories are created. Set recursive for a directory. Needs the same credentials env_exec needs.
Copy a file or directory from this host into an environment, over the same connection env_exec uses. local_path is on the host, where this server runs; guest_path is inside the guest and always uses forward slashes, Windows guests included (C:/Users/terrarium/setup.exe). Missing parent directories in the guest are created. Set recursive for a directory. Needs the same credentials env_exec needs.
Rewind an environment to a named snapshot.
Rewind an environment to the state it had right after env_fork or env_create.
Delete an environment and its disk.
Capture a running environment's screen to a PNG.
Turn the guest's mouse wheel.
Take a named snapshot of an environment.
Boot a stopped environment and wait until SSH answers. Does nothing if it is already running. Fails if no environment by that name exists - use env_fork to create one.
Type text into the guest's keyboard.
Record a VirtualBox VM that already exists on this machine as a golden image env_fork can use. The VM itself is not modified unless take_snapshot is set. Re-running it updates the record, which is how credentials are added later: adopt a machine with no user or password, fork it, read its login prompt with env_screenshot, try a guess with env_type, then adopt again with what worked. Records nothing about the guest that was not observed - never invent a user or password here.
Build a golden image from a recipe so environments can be forked from it. Slow and bandwidth-heavy: downloads roughly 500 MB the first time, then imports the appliance, boots it once for cloud-init, shuts it down and snapshots it. Takes minutes, and a Windows image takes closer to an hour because it runs a real installer. A recipe with `from` instead builds on an existing golden: it forks the base, runs the recipe's setup commands in the fork, and flattens the result into the new golden. Use recipe_list for the names that work here. Fails if the golden already exists - rebuilding one is a decision for the human.
Register an .ova or .ovf appliance file already on this machine as a golden image. Unlike golden_get there is no recipe and no download, and nothing is seeded: an appliance exported from somewhere else has no cloud-init to wait for. The VM is imported, snapshotted where it stands and recorded as a golden env_fork can use. Credentials are optional - import without them, then work the login out through env_fork, env_screenshot and env_type, and record it with golden_adopt. Creates something durable that only the user can remove, so do it when the task asks for it.
List the images that CAN be built into golden images with golden_get. This is the catalogue of what is available to build; env_list reports what has actually been built and what can be forked right now. Read-only.
No error recovery guidance. Tool descriptions do not explain what to do if a call fails. E.g., env_exec says 'run a shell command' but does not explain what happens on timeout, permission denied, or command not found. Agents have no recovery path.
List tools (recipe_list, env_list) lack pagination. No limit, offset, or cursor parameters. If hundreds of recipes or environments exist, the response could exhaust context. Baseline pattern expects page/offset + limit + total_count.