Runs

A run is one agent working in its own cloud sandbox. You pick the agent and its model, write the first prompt and describe the environment. Tracks prepares the sandbox, starts the agent and records everything it does until the run ends.

tracks runs create "Add a dark mode toggle to the settings page" \
  --harness claude-code --model claude-sonnet-5-5 \
  --repository https://github.com/alpic-ai/apps-sdk-template \
  --budget 5

The command returns right away with the run’s id. See Agents and models for every agent you can pick and the models it accepts.

In the web app, Runs → New run starts the same thing from a form, with repositories, skills, MCP servers and command-line tools picked from your library.

The environment

Everything the agent works in is fixed when the run starts.

What	What it does	Limits
Repository	A Git repository cloned before the agent starts. Without one, the agent starts in an empty folder.	One per run
Setup script	A bash script run in the repository folder after the clone and before the first prompt. If it fails, the run fails.	32,768 characters
Teardown script	A bash script run after the run ends, before the sandbox is destroyed. Its result doesn’t change how the run ended.	32,768 characters
Environment variables	Set in every process of the agent. Their values are never shown again. `PATH`, `HOME` and names starting with `ANTHROPIC_`, `CLAUDE_`, `OPENAI_`, `CODEX_` or `AGENT_RUNNER_` are reserved.	100 variables
Files	Files you upload, copied into the sandbox before setup. The first prompt tells the agent where they are.	20 files
MCP servers	Servers whose tools the agent can call. Their credentials stay with Tracks and never enter the sandbox. See MCP servers.	20 servers
Skills	Instructions the agent loads when a task calls for them, installed in its own skills folder. The repository is left untouched.	20 skills, 2 MB together
Browser	A headless Chromium in the sandbox the agent drives through an MCP server named `tracks-browser`. Screenshots of the pages it visits are kept with the run.	Claude Cowork and the Codex app use their own browser

Setup and teardown may run again if Tracks restarts mid-way: write them so running twice does no harm. The repository is any Git URL the sandbox can clone. For a private one, see Private repositories.

The sandbox is destroyed when the run ends. Anything the agent should keep, it must push or send somewhere, for example by opening a pull request.

Budget and time limit

Every run has both. Reaching either one ends the run.

	Default with the API, CLI and MCP	Default in the web app	Range
Budget	$20	$1	$0.01 to $10,000
Time limit	2 hours	10 minutes	1 minute to 12 hours

The budget counts what the run spends on model calls and sandbox time. A run can go slightly over it, by the requests already in flight when the budget is reached.
The time limit counts from when the run starts, setup included. It stops the agent even in the middle of a prompt.

tracks runs create "..." --harness codex --model gpt-5.5 --budget 2 --time-limit 1800

One prompt, or a conversation

By default a run is one-shot: it ends as soon as the agent finishes its first prompt. Add --no-one-shot to keep chatting with the agent (one_shot: false in the API). After each prompt, the run waits idle with its sandbox kept, and you send follow-ups:

tracks runs create "Read the codebase and list what could be simplified" \
  --harness claude-code --model claude-sonnet-5-5 \
  --repository https://github.com/alpic-ai/apps-sdk-template \
  --no-one-shot

tracks runs send-prompt <id> "Do the first one"
tracks runs send-prompt <id> "Now the second" --model claude-opus-5-5

The agent continues where it stopped. A follow-up can switch to another model of the same agent. An idle run waits for its next prompt for its idle timeout: 15 minutes by default, from 2 to 15 minutes (--idle-timeout, in seconds). Then it ends. To stop a run yourself:

tracks runs end <id> ends it once its current prompt finishes.
tracks runs cancel <id> stops the agent right away, even mid-prompt.

Statuses

Status	Meaning
`preparing`	The sandbox is getting ready: clone, files, setup.
`working`	The agent is working on a prompt.
`idle`	The agent finished a prompt and waits for a follow-up.
`ended`	The run is over. Its end reason says why.

End reasons

End reason	Meaning
`completed`	The agent finished without reporting an error, or you ended the run.
`idle_timeout`	No follow-up came before the idle timeout.
`time_limit`	The run reached its time limit.
`budget_exceeded`	The run reached its budget.
`canceled`	You canceled it, or your balance reached $0.
`failed`	Something went wrong. `failure` says what, `failure_kind` what kind.

completed means the agent stopped, not that it did a good job. Read its last messages to judge its work, or use an experiment to have it judged for you.

A failed run has one of these failure_kind values:

`failure_kind`	What went wrong
`repository_checkout_failed`	The repository could not be cloned.
`setup_failed`	The setup script exited with an error.
`browser_not_started`	The browser did not start.
`agent_stopped`	The agent of a one-shot run stopped with an error.
`sandbox_not_found`	The sandbox disappeared.
`process_lost`	The agent’s process was lost.
`sandbox_unavailable`	The sandbox provider failed.
`unexpected`	Something else.

Events and frames

A run records what the agent does in two ways.

Events: read these

What the agent did, in one format for every agent: its messages, reasoning, tool calls, subagents, the pages its browser visited, and why it stopped.

Frames: raw output

Every line the agent printed, exactly as printed, in its own format. Use them to debug or find a detail events leave out.

tracks runs events <id>            # what the agent did so far
tracks runs follow <id> --events   # print events as they happen, until the run ends
tracks runs frames <id>            # the raw output

Each event points to the frames it was read from. The last event of every prompt is a stop, saying whether the agent completed, failed or was canceled. In the web app, a run’s page shows the same thing in its Conversation tab, the tools it used in Agent Tools, and its settings in Configuration.

Labels

Attach labels to a run to find it again, such as ticket:ENG-42, with --label ticket:ENG-42 on tracks runs create or labels in the API. Then list runs by label with tracks runs list --label ticket:ENG-42, or GET /runs?label=ticket:ENG-42. Tracks never reads them. Up to 19 labels of yours per run: Tracks adds started_by, the API key that started it. Tracks sets some labels itself: started_by names the API key that created the run, and runs of an experiment carry experiment, execution and slot.

What it costs

tracks runs usage <id> shows what the run consumed, tokens per model and sandbox time, and what it cost. Runs are paid from your organization’s balance, and start only while it is above $0. See Billing.

Get started

Concepts

Guides

The environment

Budget and time limit

One prompt, or a conversation

Statuses

End reasons

Events and frames

Events: read these

Frames: raw output

Labels

What it costs

​The environment

​Budget and time limit

​One prompt, or a conversation

​Statuses

​End reasons

​Events and frames

Events: read these

Frames: raw output

​Labels

​What it costs

The environment

Budget and time limit

One prompt, or a conversation

Statuses

End reasons

Events and frames

Labels

What it costs