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

# evolve run

> Start a job, and optionally follow it to the end.

```bash theme={"dark"}
evolve run [options]
```

Start a job. `evolve run` is the short form of `evolve job start`, and both take the same options.

```bash theme={"dark"}
evolve run \
  -d terminal-bench-4@4.0 \
  -a codex \
  -m gpt-6-astra \
  -k 2 \
  -l 5 \
  --watch
```

## What to run

<ParamField path="-d, --dataset" type="name[@version]">
  Dataset to run. Repeatable. A bare name means the active version.
</ParamField>

<ParamField path="-i, --include-task-name" type="glob">
  Include filter over task names, applied to every dataset. Repeatable.
</ParamField>

<ParamField path="-x, --exclude-task-name" type="glob">
  Exclude filter over task names, applied to every dataset. Repeatable.
</ParamField>

<ParamField path="-l, --n-tasks" type="n">
  Cap the task count of each dataset after the filters.
</ParamField>

<ParamField path="-a, --agent" type="name[@version]">
  Agent, built-in or registered.
</ParamField>

<ParamField path="-m, --model" type="name">
  Model. Repeatable; each model is one arm.
</ParamField>

<ParamField path="-k, --n-attempts" type="n" default="1">
  Attempts per task and arm.
</ParamField>

<ParamField path="-n, --n-concurrent" type="n" default="4">
  Parallel trials, 1 to 150.
</ParamField>

<ParamField path="-e, --env" type="provider" default="daytona">
  Sandbox provider: `e2b`, `daytona` or `modal`.
</ParamField>

<ParamField path="--job-name" type="name">
  User-facing label. Generated by the server when omitted.
</ParamField>

## The arm

Each of these applies to every arm of the job.

<ParamField path="--effort" type="value">
  Reasoning effort for every arm, applied verbatim. The values each harness accepts are on the [models](/core-concepts/models#reasoning-effort) page and in the [capability document](/sdk-reference/meta). An agent that cannot honor the value is refused, never silently skipped.
</ParamField>

<ParamField path="--preset" type="name">
  Named settings preset for every arm: `no-internet` turns the vendor's server-side web tools off, `pinned-context` fixes the context window at 200000 tokens. Only `claude` and `codex` take one; a preset wins over `--ak config` where they disagree. An unknown name is refused with `invalid_input`, a preset the agent cannot guarantee with `agent_preset_unsupported`.
</ParamField>

<ParamField path="--agent-kwarg, --ak" type="key=value">
  Agent kwarg for every arm, as `key=value`, repeatable. The delivered key is `config`: `--ak 'config=<path|inline JSON>'` becomes the harness's native settings file, your document as the base and the platform's routing on top; a path is read locally, as JSON or as TOML for a Codex config. Only `claude` and `codex` take a config. A key other than `config` is refused with `agent_kwarg_unsupported`, a config on another harness with `agent_config_unsupported`, and a key touching billing, base URL, routing or env with `agent_config_key_refused`.
</ParamField>

<ParamField path="--skills, --skill" type="ref | path">
  Skill for every agent arm. Repeatable. Accepts `skills.sh/<owner>/<repo>[/<skill>]`, `org/repo[@ref]`, an https git URL, `upload:<id>`, `name:<skill-name>` (your moving name pointer, resolved server-side), or a local folder, which is uploaded first and then referenced; `--print-config` still shows the path you typed.
</ParamField>

<ParamField path="--ve, --verifier-env" type="KEY=VALUE">
  Environment for every verifier run. Repeatable. The server honors exactly `REWARDKIT_JUDGE` and `REWARDKIT_MODEL`, rewardkit's judge override, and refuses any other key.
</ParamField>

<ParamField path="--secret" type="NAME[@LABEL][=ENVNAME]">
  Attach one of your stored env secrets to every agent run. Repeatable. `NAME` is the stored secret's name.

  `@LABEL` picks a labeled row; omitted, the `default` row or the only row, and several labels with no `default` is refused as ambiguous. `=ENVNAME` renames the env var inside the sandbox. References only: the value never rides the command line or the wire.
</ParamField>

<ParamField path="--secret-inline" type="NAME[@LABEL]:DELIVERY=VALUE">
  Save `VALUE` into your vault as an env secret and attach it to this job in one step. Repeatable. `DELIVERY` is `brokered` or `direct` and sits before `=`, so everything after the first `=` is the value, byte for byte. `@LABEL` defaults to `default`.

  Restating an existing secret exactly attaches it, so re-running the same command converges; a different value or delivery is refused as `secret_exists`. The job stores only the reference.
</ParamField>

## Spend and retries

<ParamField path="--max-trial-spend" type="usd">
  Model-spend cap for each trial. Defaults to the server's, \$200.
</ParamField>

<ParamField path="-r, --max-retries" type="n">
  Max automatic retries per trial on infrastructure errors. Defaults to 2; `0` turns retries off. Each attempt carries the full trial cap. Over a `-c` file it overrides only its own field of `retry`.
</ParamField>

<ParamField path="--retry-include" type="exception">
  Exception types to retry on. Repeatable. The names are `AgentAuthenticationError` (a gateway credential refusal), `ModelNotFoundError` (a model that never served) and `InfrastructureError` (everything else). Defaults to everything `--retry-exclude` admits.
</ParamField>

<ParamField path="--retry-exclude" type="exception">
  Exception types not to retry on. Repeatable, and it wins over `--retry-include`. Defaults to the platform's non-retryable set; an explicit `null` in a `-c` file's `retry` turns exclusions off entirely.
</ParamField>

## Embedded analysis

<ParamField path="--analyze">
  Analyze each trial's trace server-side as it settles. Cancelled trials are skipped. Bare, it uses the platform's analyze model, rubric and prompt.
</ParamField>

<ParamField path="--analyze-model" type="name">
  Model the analyzer runs. Must be on the `claude` roster. Implies `--analyze`.
</ParamField>

<ParamField path="--analyze-rubric" type="path">
  Rubric file for the analyzer: TOML, YAML or JSON in the `{criteria}` shape. Implies `--analyze`.
</ParamField>

<ParamField path="--analyze-prompt" type="path">
  Prompt file for the analyzer. Replaces the built-in prompt. Implies `--analyze`.
</ParamField>

<ParamField path="--analyze-provider" type="provider">
  Sandbox provider the analyzer runs on. Defaults to the platform's analysis default. Implies `--analyze`.
</ParamField>

<ParamField path="--analyze-effort" type="value">
  Reasoning effort the analyzer runs at. Defaults to the per-model default: `high` on `openrouter/deepseek/deepseek-v4.1-flash`, `max` on `glm-5.3-flash`. Implies `--analyze`.
</ParamField>

## Timeouts

<ParamField path="--timeout-multiplier" type="x" default="1.0">
  Multiplier for task timeouts, any finite number above 0; below 1 shrinks. It multiplies each task's declared timeouts for this job only; the task is never rewritten. A product past 2,147,483,647 ms is refused at create. Resumed and retried jobs inherit the multipliers.
</ParamField>

<ParamField path="--agent-timeout-multiplier" type="x">
  Multiplier for the agent execution timeout. Overrides `--timeout-multiplier`.
</ParamField>

<ParamField path="--verifier-timeout-multiplier" type="x">
  Multiplier for the verifier timeout. Overrides `--timeout-multiplier`.
</ParamField>

<ParamField path="--agent-setup-timeout-multiplier" type="x">
  Multiplier for the agent setup timeout. Overrides `--timeout-multiplier`.
</ParamField>

<ParamField path="--environment-build-timeout-multiplier" type="x">
  Multiplier for the environment build timeout. Overrides `--timeout-multiplier`.
</ParamField>

## Config file and output

<ParamField path="-c, --config" type="path">
  Job config file, YAML or JSON with the same field names `jobs().start()` takes. Explicit flags override its fields one at a time, inside the `retry` and `analyze` objects too. The file may be partial: `-d` and `-a`/`-m` can supply what it omits, but a selector inside it needs `name` and an arm needs `name` and `model_name`.

  YAML is read with the 1.1 schema (`yes` and `on` are booleans, `012` is octal), and a duplicate key, a second document or an unknown tag refuse with a line number. The body is checked before any request: an unknown key is refused by name, a string must be a string (quote `version: "1.10"`), `n_attempts` and `n_tasks` are at least 1, `n_concurrent_trials` is 1 to 150, `job_name` is at most 200 characters. A bare date or `.inf` is refused rather than rewritten.
</ParamField>

<ParamField path="--print-config">
  Print the resolved job body as JSON and exit without running.
</ParamField>

<ParamField path="--watch">
  Stream events until the job finishes.
</ParamField>

<ParamField path="-q, --quiet">
  With `--watch`: suppress the event log and print the final block only.
</ParamField>

<ParamField path="-y, --yes">
  Accepted for compatibility. Hosted runs have no prompt to confirm.
</ParamField>

## Global options

<ParamField path="--json">
  Machine-readable JSON output.
</ParamField>

<ParamField path="--api-key" type="key">
  API key. Defaults to `$EVOLVE_API_KEY`.
</ParamField>

<ParamField path="--base-url" type="url">
  API base URL. Defaults to the Evolve dashboard API.
</ParamField>