← sources

Terrarium – Local VMs for AI agents with explicit permissions

source: reddit (reddit:LocalLLaMA)published 2026-11-07 13:55ingested 2026-11-08 02:39

retained text

I wanted a secure way to run AI agents against my local models without giving them my whole machine. Something in the spirit of [pi](https://pi.dev/): simple, narrow and auditable, yet flexible. What I found tried to do too much, so I built **Terrarium**.

It runs agents in persistent Linux VMs ("boxes") on your machine. A YAML recipe says which host folders a box can read or change and which network destinations it can reach. Everything else is blocked, for every process in the VM: the agent, and any tool or script it launches.

**Example: an agent with one project folder and your local Ollama**

    mounts:
      - host: .
        guest: /work
    network:
      allow:
        - dl-cdn.alpinelinux.org:443   # package installs in on_create
        - ollama.host:11434
      hosts:
        - { name: ollama.host, addr: HOST_LOOPBACK }
    hooks:
      on_create: [apk add --no-cache git nodejs npm]
    workload:
      entrypoint: /bin/sh
      workdir: /work

Inside the box, `http://ollama.host:11434` reaches Ollama on your host (even if it only listens on `127.0.0.1`). Other host ports are refused, and public names don't resolve unless you allow them. An empty recipe shares no folders and allows no network at all.

    terra ./dev.yaml setup   # create the box and install the tools
    terra                    # open a shell in the box at /work

**Why not Docker or a raw VMM?** Each box is a full VM with its own kernel, not a container sharing yours. And unlike Firecracker or Cloud Hypervisor, it's a ready-to-use tool: one binary, no daemon, the same recipe on Linux, macOS and Windows, with network policy enforced outside the VM.

**In daily use**

* **Persistent boxes:** install your tools once; they and the box's files survive restarts.
* **Built-in terminal multiplexing:** attach from several terminals, detach without stopping the agent, reconnect later.
* **One executable:** `terra` bundles the VM components, a Linux kernel and an Alpine base system.
* **Light:** on my Linux machine an existing box boots and runs its first command in under 200 ms, and an idle box uses about 45 MB of host memory.

**Under the hood**

* **Sandboxed device code:** a small custom VMM built on parts of rust-vmm. Filesystem, block and network devices run as WebAssembly components, each with its own memory limit and a restricted set of host functions.
* **Separate network broker:** the VM process has no network access. Connections go through a sandboxed broker that checks them against the recipe.
* **Generated seccomp allowlists:** Linux builds use per-role syscall allowlists generated by static analysis of the binaries.

**Limits:** the permissions you grant still matter. An agent can delete files in a writable share, read credentials you pass in, and send data to allowed destinations. There are no CPU, memory or disk quotas on the host yet; I'm not sure people want them. Details: [security model](https://github.com/terrarium-sh/terrarium/blob/main/docs/security.md).

It's Apache-2.0 and in beta, but don't let that put you off: it should already serve you well. It runs on Linux (amd64/aarch64 with KVM), Apple Silicon macOS and Windows (amd64 with Windows Hypervisor Platform). There's a Windows arm64 build too, but I can't test it. The CLI should stay stable; on-disk formats may still change.

* Repo and quickstart: [https://github.com/terrarium-sh/terrarium](https://github.com/terrarium-sh/terrarium)
* Example recipes: [https://github.com/terrarium-sh/terrarium\_examples](https://github.com/terrarium-sh/terrarium_examples)

I'd especially like to hear where getting your agent and local model running breaks down: installation, missing network permissions, or tools that don't fit the guest.

*Note: I meant to share this in the biweekly project thread, but there isn't one up this time, so I'm posting it on its own. Hope that's okay.*

document fetched 2026-11-08 00:34 · canonical https://reddit.com/r/LocalLLaMA/comments/1xq6xqg/terrarium_local_vms_for_ai_agents_with_explicit