> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracks.alpic.ai/llms.txt > Use this file to discover all available pages before exploring further. # Runs > One coding agent working on your prompt in its own sandbox, recorded from start to end 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. ```bash theme={null} 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](https://docs.tracks.alpic.ai/concepts/agents.md) for every agent you can pick and the models it accepts. > [!TIP] > > 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](https://docs.tracks.alpic.ai/guides/mcp-servers.md). | 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](https://docs.tracks.alpic.ai/guides/private-repositories.md). > [!NOTE] > > 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. ```bash theme={null} 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: ```bash theme={null} 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 "Do the first one" tracks runs send-prompt "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 ` ends it once its current prompt finishes. * `tracks runs cancel ` 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. | > [!WARNING] > > `completed` means the agent stopped, not that it did a good job. Read its last messages to judge its work, or use an > [experiment](https://docs.tracks.alpic.ai/concepts/experiments.md) 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. ```bash theme={null} tracks runs events # what the agent did so far tracks runs follow --events # print events as they happen, until the run ends tracks runs frames # 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 ` 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](https://docs.tracks.alpic.ai/concepts/billing.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.