> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trelent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs

A run is one execution of a prompt inside a sandbox. Each run has:

* A sandbox (the Docker image the agent runs on)
* A harness + model (the agent framework and LLM)
* A prompt (instructions for the agent)

## Create a run

```python theme={null}
from trelent_agents import Client, ClaudeCodeHarnessSpec

client = Client(client_id="...", client_secret="...")

run = client.runs.create(
    sandbox="translator:latest",
    harness=ClaudeCodeHarnessSpec(model="claude-sonnet-4-6"),
    prompt="Translate 'Hello world' to Spanish.",
)
```

`harness` is optional — it defaults to `ClaudeCodeHarnessSpec()`. See [Harnesses](/agents/harnesses).

### Timeout

Runs have a default timeout of 1 hour. Override with `timeout_seconds` (min 60, max 86400):

```python theme={null}
run = client.runs.create(
    sandbox="translator:latest",
    prompt="...",
    timeout_seconds=600,
)
```

## Get a run

```python theme={null}
run = client.runs.get("run_1234567890")
```

## List runs

```python theme={null}
runs = client.runs.list()
runs = client.runs.list(sandbox="translator:latest")
```

## Poll for completion

```python theme={null}
while run.status not in ("completed", "failed", "cancelled"):
    run.refresh()
```

## Run status

A run's `status` is one of:

| Status      | Meaning                                  |
| ----------- | ---------------------------------------- |
| `pending`   | Queued, not yet running                  |
| `running`   | Actively executing                       |
| `completed` | Finished successfully                    |
| `failed`    | Finished with an error (see `run.error`) |
| `timeout`   | Exceeded `timeout_seconds`               |
| `cancelled` | Cancelled via `client.runs.cancel(...)`  |

## Get the result

Once `run.status` is `"completed"`, the final response is available at `run.result.output`:

```python theme={null}
print(run.result.output)
# => "Hola, mundo."
```

## Cancel a run

```python theme={null}
client.runs.cancel(run.id)
```