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

# Configure a scenario

> Choose the repository, coding agent, persona, and tools that make a Gauge Agents run representative.

A **scenario** defines the environment used to run a measurement. The web app and current CLI use this name; older documentation may call it a **run preset**. A **schedule** controls recurring execution and sampling.

Keep the task and pass criteria separate from the scenario so you can compare environments without changing what success means.

## Choose the inputs

| Input           | What to decide                                                                                                                               |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Repository      | Use the codebase a developer would have, or the default scaffold for a small task. Pin a Git ref when you need a stable comparison.          |
| Agent and model | Choose a supported configuration. Omitting a model pin uses the available default; record the model shown on the run when comparing results. |
| Persona         | Choose the simulated user behavior appropriate to the task.                                                                                  |
| Skills          | Add the specific skill versions the developer's agent should receive.                                                                        |
| MCP servers     | Add the prepared server versions the task needs and confirm their authorization.                                                             |
| Credentials     | Grant access only to the service needed by the task. See [Credentials](/agents/concepts/credentials).                                        |

For private repositories, confirm that the repository is accessible through your organization's configured repository connection before running. A private URL by itself does not grant access. For provider-key requirements, check the provider configuration in Settings and your billing workload eligibility.

## Create and attach a scenario

The following example uses the default scaffold and the default available Claude Code model:

```bash theme={null}
gauge scenarios create --name "Basic coding task" --agent claude-code
gauge scenarios list
```

Copy the scenario ID and an existing eval ID into:

```bash theme={null}
gauge evals scenarios add <eval-id> --scenario <scenario-id>
gauge evals get <eval-id>
```

Review the confirmation and schedule before adding the scenario: it changes which configurations future scheduled runs use. To test an environment once without attaching it, use the quickstart's [one-off run](/agents/quickstart#launch-and-inspect-one-eval).

## Add a repository or tools

Use `gauge repos`, `gauge skills`, and `gauge mcp` to inspect available resources. `gauge scenarios create --help` lists the supported flags, including `--repo`, `--ref`, `--skill`, and `--mcp`.

Use actual available resource IDs and versions. Launch one run and inspect its logs before expanding across many measurements. If setup fails, use [Run troubleshooting](/agents/guides/troubleshooting-runs).