> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Provider-aware execution plan rewrites before environment startup.

Recipes connect benchmark task metadata to provider-specific environment settings. They run after the default execution plan is built and before the environment starts.

Use recipes when a heavy benchmark needs task images, snapshots, workspace layout, resource hints, or compatibility checks that should not be hard-coded in benchmarks or CLI commands.

## What Recipes Own

<CardGroup cols={2}>
  <Card title="Image selection" icon="package">
    Read public Docker image metadata or provider snapshots and set provider params.
  </Card>

  <Card title="Workspace layout" icon="folder-tree">
    Align benchmark workspaces such as `/testbed`, `/workspace`, or `/root`.
  </Card>

  <Card title="Resource hints" icon="cpu">
    Merge task CPU, memory, disk, GPU, or provider resources without overwriting explicit user overrides.
  </Card>

  <Card title="Compatibility failure" icon="shield-alert">
    Fail before sandbox startup when a required image, snapshot, or task metadata field is missing.
  </Card>
</CardGroup>

Recipes do not execute commands, create sandboxes, score results, or call model APIs.

## Core Interface

| Method                     | Responsibility                                                                   |
| -------------------------- | -------------------------------------------------------------------------------- |
| `matches(req, task, plan)` | Return true when the recipe applies to this benchmark, provider, task, and plan. |
| `apply(plan, req, task)`   | Return a new `ExecutionPlan` with provider-aware overrides.                      |

Recipes are registered by id. The runtime can apply default recipes automatically, or restrict recipes through `--recipe`.

## External Recipe Packages

Trusted private recipes can be injected for one run without adding them under `src/agentcompass`:

```text theme={null}
company_recipes/
  __init__.py
  swe_recipe.py
```

```python theme={null}
# company_recipes/__init__.py
from .swe_recipe import CompanySWERecipe

RECIPE_CLASSES = (CompanySWERecipe,)
```

The exported classes must be concrete, zero-argument `BaseRecipe` subclasses with stable ids. External classes must not use the global `@RECIPES.register()` decorator; AgentCompass adds them to a run-local registry so later SDK runs cannot see them accidentally.

```bash theme={null}
agentcompass run <benchmark> <harness> <model> \
  --recipe-dir ./company_recipes \
  --recipe company_swe_recipe
```

`--recipe-dir` is repeatable. Python callers use `recipe_dirs=["./company_recipes"]`, and config files use `runtime.recipe_dirs`. Directories are resolved from the launch working directory. Built-in recipes run first, followed by external directories and their `RECIPE_CLASSES` declaration order. Duplicate recipe ids fail before the run output directory is created.

External packages execute as trusted Python code in the AgentCompass process. They are cached by canonical path for the life of the process, are not hot-reloaded, and must already be visible on every worker filesystem. Reading an existing run through `summary` or offline analysis does not load its recorded external packages.

## Example: Modal SWE-bench Verified

```bash theme={null}
export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

The `swebench_verified_modal_prebaked` recipe can derive the image from SWE-bench metadata or instance id and set the workspace root to `/testbed`.

## Example: Daytona Terminal-Bench

```bash theme={null}
export DAYTONA_API_KEY="..."

agentcompass run \
  terminal_bench_2 \
  terminus2 \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["overfull-hbox"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

The Terminal-Bench Daytona recipe reads `task.environment.docker_image`, sets the environment image, and uses `/root` as the default workspace root.

## User Overrides

| Override                               | Effect                                                               |
| -------------------------------------- | -------------------------------------------------------------------- |
| `--env-params '{"image":"..."}'`       | Force a provider image when the recipe supports registry images.     |
| `--env-params '{"named_image":"..."}'` | Use a named Modal image when supported.                              |
| `--env-params '{"snapshot":"..."}'`    | Use a provider snapshot instead of an inferred image when supported. |
| `--recipe <recipe_id>`                 | Restrict enabled recipes to explicit ids.                            |
| `--recipe-dir <package_dir>`           | Load a trusted external recipe package for this run; repeatable.     |

Do not pass `image` just because a benchmark is remote. If a recipe can infer the task image, the shorter command is more reproducible.

## Recipe Families In This Repo

| Benchmark family                  | Providers                                    |
| --------------------------------- | -------------------------------------------- |
| SWE-bench Verified                | `host_process`, `docker`, `modal`, `daytona` |
| SWE-bench Multilingual / Pro      | `docker`, `modal`, `daytona`                 |
| Terminal-Bench 2                  | `modal`, `daytona`                           |
| PinchBench / SkillsBench / GDPval | provider-specific cluster or gateway recipes |

## Developer Notes

Add a recipe when the compatibility rule is the combination of benchmark, task metadata, and provider. If the setting is provider-wide, put it in environment config. If the setting is scoring-related, keep it in the benchmark.

## Related Pages

* [Environments](/key_modules/environments)
* [Benchmarks](/key_modules/benchmarks)
* [Runtime Extensions](/developer/runtime_extensions)