Quickstart

  1. Prerequisites
  2. Run it
  3. Give it a credential
  4. Your first agent
  5. Lock down what it can reach
  6. Next steps

Prerequisites

  • Docker — runs the sandbox.
  • Python 3.13 + uv — runs the orchestrator.
  • bun — runs the console.

Rust is only needed to build or test Warden outside Docker; make build compiles it inside the sandbox image’s multi-stage build.

Run it 

git clone https://github.com/OAISP/terrarium.git
cd terrarium

make setup        # install orchestrator deps (uv sync)
make build        # build the sandbox image — includes the Rust Warden (multi-stage)
make network      # create the isolated agent docker network
make run          # start the orchestrator (FastAPI, :8900)
make web          # in another shell: install web deps + start the console (:3737)

Open http://localhost:3737.

With no auth token set the console is open for local development. Set TERRA_TOKEN to require a bearer token; the orchestrator refuses to start on a non-loopback bind without one, so you cannot accidentally expose an unauthenticated admin API.

Give it a credential

Two paths, and the choice matters — read the terms-of-service note before picking the second.

API key (no ToS restriction):

export ANTHROPIC_API_KEY=sk-ant-...
make run

Subscription: paste the contents of ~/.claude/.credentials.json into the console’s credential badge. It is sealed at rest and injected by Warden.

Either way the real credential never enters the sandbox — the agent sees a realistic decoy.

Your first agent

  1. Agents → New agent. Pick a model and a persona, or start from a template.
  2. Sessions → New session. Choose the agent, type what you want it to do, and launch.
  3. Watch the transcript stream. The inspector rail on the right shows sub-agent activity, token composition, and any files the agent wrote (each one downloadable).

Lock down what it can reach

By default a new session inherits the global egress policy. To narrow it:

  1. Boundary → Egress → New profile (or start from a preset — Developer, Python, Node, Data science…).
  2. Boundary → Environments → New environment, and attach the profile.
  3. Edit the agent and attach that environment.

Attaching an environment does two different things, and the asymmetry is deliberate: secrets are scoped (the agent gets only those), while egress profiles merge (enforce wins, allowed hosts union) — so attaching can widen reach, never narrow it.

The Egress page shows live Warden decisions as they happen, and the header carries a kill switch that freezes all egress — including Anthropic — for every running session.

Next steps

  • Configuration — the environment variables that matter.
  • SDK — drive all of this from Python.
  • Deployment — running it somewhere other than your laptop.