Environment

.env loading

At startup, the CLI loads .env from the project root. Values already set in your shell win; .env supplies only missing values.

# .env
ANTHROPIC_API_KEY=sk-ant-...
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://example.services.ai.azure.com/openai/v1/
AZURE_OPENAI_API_VERSION=2024-10-21
TOGETHER_API_KEY=...
MORPH_API_KEY=...

Don't commit .env — the project template adds it to .gitignore.

Provider credentials

Which variables are required depends on which models appear in your agent configs.

Model routing depends on the harness path. See Providers.

Run-control paths

The run-control CLI and web status surface accept explicit paths for mutable operational state and persisted plans:

uv run aec-bench run status <run-id> \
  --operational-store artefacts/operational.sqlite \
  --plan-root artefacts/runs

In --dev mode, the launcher passes these paths to the reloadable FastAPI process through environment variables:

The web status route is GET /api/runs/{run_id}/status. The TUI run-progress view reads the same two roots.

Agent runtime overrides

The container agent runtime reads a few environment variables, mostly for script-style and RLM adapters that pass arguments through the environment:

The harness usually sets these automatically. Custom adapter shells can override them.

Backend credentials

Keep these credentials in the shell, .env, or the provider's own auth store. Do not put secrets in experiment YAML.

File layout

A new project contains the files and directories that aec-bench init creates directly:

project_root/
├── aec-bench.toml              # project config
├── suite.toml                  # example generated-suite config
├── .gitignore
├── .claude/
│   └── skills/
│       ├── add-task/
│       ├── configure-experiment/
│       ├── create-dataset/
│       ├── create-template/
│       ├── domain-check/
│       ├── hardening-pass/
│       └── meta-harness/
├── .agents/
│   └── skills/                 # the same seven packaged skills
├── tasks/                      # includes one example unless --no-example
├── seeds/
├── artefacts/
│   ├── ledger/
│   └── datasets/

Create .env yourself when the project needs credentials; .gitignore already excludes it. Authoring and execution commands create or consume configured paths such as jobs/, templates/, and artefacts/feedback/ when needed.

Use aec-bench init --update-skills to refresh the seven packaged skills in .claude/skills/ and .agents/skills/ while preserving other skill directories.

Global user config

Per-user path defaults live at ~/.config/aec-bench/config.json:

{
  "tasks_root": "tasks",
  "ledger_root": "artefacts/ledger",
  "feedback_root": "artefacts/feedback",
  "jobs_root": "jobs",
  "datasets_root": "artefacts/datasets"
}

Managed via aec-bench config view|set|reset. Project-level settings take precedence over these path defaults. The project loader also has built-in defaults for source-only paths such as templates_root and seeds_root.

Precedence

Path settings resolve in this order (highest wins):

1. CLI path flag such as --tasks-root
2. Project config (aec-bench.toml)
3. Global user config (~/.config/aec-bench/config.json)
4. Built-in defaults

Compute selection is separate. A config-based run uses compute.backend from experiment.yaml. An inline run uses --backend and defaults to modal.

Environment variables bypass the path ladder. They are either credentials required by provider SDKs at call time or agent-runtime overrides read by a container entry script.

Treat source tasks, datasets, and evolution workspaces as the source of truth. Regenerate local Prime packages and swarm outputs when those sources change.