Skip to main content
TerminalUse is easiest to understand when you start from the resource model instead of the API surface.

​
The Primitives

PrimitiveWhat it isWhy it matters
NamespaceYour isolation boundary for compute and storageMost teams start with one namespace
ProjectA collaboration and permission boundary for filesystemsUseful for customer- or workflow-level access control
FilesystemPersistent files mounted into tasks at /workspaceShared storage across tasks
AgentYour deployed Python runtimeEach deploy creates a new version
EnvironmentA named deployment policy, such as production or previewBranch rules resolve branches into environments
BranchA deployment slot for a git branchA branch points at the current active version
VersionOne deployed build of an agentTasks are created against a specific version
TaskOne running conversation or unit of workHolds state, messages, events, and an optional filesystem mount
EventInput sent to a taskUsually user text or structured data
MessageOutput emitted by the agentUsually assistant text, UI parts, or streamed tool output
StatePer-task persisted JSONUsed for continuity across turns

​
The Two Loops

​
Deploy Loop

  1. Write or change agent code.
  2. Run tu deploy.
  3. TerminalUse creates a new version.
  4. That version becomes active on the branch’s environment.
See Deployments.

​
Run Loop

  1. Create or choose a filesystem.
  2. Create a task against an agent.
  3. Send events to the task.
  4. Read streamed messages and persisted state.
  5. 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:
PathPurpose
/workspaceThe mounted filesystem
/root/.claudeTask-scoped Claude state when used
/root/.codexTask-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.