Python SDK

pip install terrarium-python

The distribution is terrarium-python; the import package is terrarium.

An async client for the orchestrator API. The surface mirrors the Claude Agent SDK — query, TerrariumOptions, typed messages, can_use_tool — with extra parameters for Terrarium’s own features. Like the Claude Agent SDK it is async-only, and its sole dependency is httpx.

import asyncio
from terrarium import TerrariumClient, TerrariumOptions, AssistantMessage, TextBlock

async def main():
    async with TerrariumClient("https://terrarium.example.com", token="…") as client:
        async with client.session(options=TerrariumOptions(model="claude-haiku-4-5")) as s:
            async for msg in s.receive_response("What is 7 × 6?"):
                if isinstance(msg, AssistantMessage):
                    for block in msg.content:
                        if isinstance(block, TextBlock):
                            print(block.text)

asyncio.run(main())

Mental model

Concept	What it is	Lifetime
Client	a connection to one orchestrator (`base_url` + bearer `token`)	your process
Agent	a reusable, stored config — model, persona, egress, allowed tools	persistent; `client.agents`
Session	one running conversation in a fresh sandbox; inherits an agent’s config, or takes an inline one	ephemeral by default, or durable
Client tool	a tool whose handler runs in your process, callable by the sandboxed agent	per-session
Environment	a named `{secrets, egress profile}` bundle an agent attaches to	persistent; `client.environments`

TerrariumOptions is a superset of the Claude SDK’s ClaudeAgentOptions. It exposes the same configurability as the console — a parity test enforces that, so a field the API accepts can never be missing here. Only the fields you set are sent; everything else is the orchestrator’s default.

Client tools

The one capability worth calling out: a tool whose handler runs in your process, with your application context, callable by the sandboxed agent. Only the agent’s tool input crosses out, your handler runs on your side, and only the result you return crosses back in. Your code, state and secrets never enter the sandbox.

CLI

The package installs terra-cli for scripting and CI:

terra-cli sessions list
terra-cli verify-egress <session-id>   # recompute a session's audit hash chain

Full reference — every resource, streaming, rewind, uploads, downloads, egress profiles and error types — lives in sdk/README.md.