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

# Start a run

> Run an agent against a benchmark dataset.

Start a benchmark with an installed agent.

<CodeGroup>
  ```bash CLI theme={null}
  valkyrie run start --agent sweagent --benchmark swebench
  ```

  ```python Python SDK theme={null}
  run = await client.runs.start(
      agent="sweagent",
      benchmark="swebench",
  )
  ```
</CodeGroup>

The tracker accepts the run and returns its id. Every option, alias, default, and constraint is in the [`valkyrie run start`](/reference/cli/run#start) and [`client.runs.start`](/reference/sdk/runs#start) reference.

## Decide the run scope

A run covers the whole dataset unless you narrow it. Narrow by task id when you know which tasks matter, or by slice for a cheap smoke run:

```bash theme={null}
valkyrie run start --agent sweagent --benchmark swebench --slice "0:10"
```

To select ids explicitly, export the dataset's task ids first with [`valkyrie benchmark tasks`](/reference/cli/benchmark#tasks), then pass them with `--task-ids` or `--task-ids-file`.

`--concurrency` sets how many sandboxes run at once. Raising it shortens wall-clock time and raises simultaneous provider and model cost.

## Map secrets instead of passing values

```bash theme={null}
valkyrie run start --agent sweagent --benchmark swebench -s ANTHROPIC_API_KEY AnthropicApiKey
```

`-s` maps an environment variable to an AWS Secrets Manager secret name. It never accepts the raw secret value. A CLI mapping overrides the agent contract's mapping for the same environment variable.

## Stream progress as the run starts

```bash theme={null}
valkyrie run start --agent sweagent --benchmark swebench --connect
```

Without `--connect`, attach later with [`valkyrie run fetch`](/reference/cli/run#fetch). See [Monitor runs](/runs/monitor) for reading the stream.

## Start repeated runs

```bash theme={null}
valkyrie run start --agent sweagent --benchmark swebench --count 3
```

Start requests are sent sequentially. Accepted runs execute independently and may overlap. `--connect` is rejected when `count` is greater than 1.

<Warning>
  Approximate simultaneous task pressure and cost can scale with `count × concurrency`.
</Warning>

Starts are fail-fast: after one request fails, the CLI does not attempt later requests. A transport failure can leave the latest request's outcome unknown; verify with `valkyrie run list`.