Core Model

Terminal Use is easiest to understand when you start from the resource model instead of the API surface.

The Primitives

Primitive	What it is	Why it matters
`Namespace`	Your isolation boundary for compute and storage	Most teams start with one namespace
`Project`	A collaboration and permission boundary for filesystems	Useful for customer- or workflow-level access control
`Filesystem`	Persistent files mounted into tasks at `/workspace`	Shared storage across tasks
`Agent`	Your deployed Python runtime	Each deploy creates a new version
`Environment`	A named deployment policy, such as `production` or `preview`	Branch rules resolve branches into environments
`Branch`	A deployment slot for a git branch	A branch points at the current active version
`Version`	One deployed build of an agent	Tasks are created against a specific version
`Task`	One running conversation or unit of work	Holds state, messages, events, and an optional filesystem mount
`Event`	Input sent to a task	Usually user text or structured data
`Message`	Output emitted by the agent	Usually assistant text, UI parts, or streamed tool output
`State`	Per-task persisted JSON	Used for continuity across turns

The Two Loops

Deploy Loop

Write or change agent code.
Run tu deploy.
Terminal Use creates a new version.
That version becomes active on the branch’s environment.

See Deployments.

Run Loop

Create or choose a filesystem.
Create a task against an agent.
Send events to the task.
Read streamed messages and persisted state.
Pull the filesystem back out if you need the results locally.

See Task Lifecycle.

What Gets Mounted Into Runtime

When a task runs with a filesystem attached, the runtime sees:

Path	Purpose
`/workspace`	The mounted filesystem
`/root/.claude`	Task-scoped Claude state when used
`/root/.codex`	Task-scoped Codex state when used

Agent code itself is mounted separately and read-only inside the sandbox.

One Important Distinction

The Python SDK is the public agent runtime surface. The TypeScript and Python clients are for calling deployed agents and managing resources from your app or backend. Use Building Agents for the runtime model and Using Agents for app-side integration.

Get Started

Core Concepts

Build Agents

Deploy & Operate

Security & Access

API

The Primitives

The Two Loops

Deploy Loop

Run Loop

What Gets Mounted Into Runtime

One Important Distinction

​The Primitives

​The Two Loops

​Deploy Loop

​Run Loop

​What Gets Mounted Into Runtime

​One Important Distinction

The Primitives

The Two Loops

Deploy Loop

Run Loop

What Gets Mounted Into Runtime

One Important Distinction