Configuration field reference#

The framework merges built-in defaults, your YAML, and command-line overrides, in that order. This page covers every field in the default configuration. Method-specific parameters are included directly from their manifests in the learning-method pages.

Paths, values, and overrides#

Filesystem paths interpreted by the framework are relative to the config file’s directory, not the shell’s working directory. They support home and environment-variable expansion through the config path resolver. File callables such as pipeline.py:run also resolve against the config directory. Dotted Python modules use the active Python environment. Values inside free-form method parameters can have their own path rules.

hermit train --config path/to/run.yaml trainer.run_name=trial-02 data.step_size=4
hermit eval --config path/to/run.yaml --adapter final trainer.run_name=trial-02 eval.repeats=3

Overrides are YAML values; quote shell-sensitive lists and dictionaries. Unknown framework keys are rejected. evolver.params, agent.params, pipeline.params, llm and backends are free-form mappings at merge time; this is not a guarantee that their consumer supports arbitrary fields.

Data and task#

Field

Type / default

Meaning and constraints

data.tasks

path / null; required

JSONL with unique id or task_id values

data.train

path / null; required

One training task id per line

data.val

path / null

Validation ids; required by methods declaring validation-data needs

data.test

path / null

Test ids; a nonempty test split is required by eval

data.step_size

integer / 8

Positive number of task executions in a main training batch

data.shuffle

boolean / true

Shuffle training order; set false for ordered streams

data.shuffle_seed

integer / 0

Training shuffle seed; does not seed every model or method

task_info

directory / null

Learner-facing task description; provide README.md

agent.name

string / null; required

Built-in react, codex, claude-code, pi, mini-swe-agent, opencode, dsh, hermes, harbor (a benchmark’s task set in Harbor’s format, see Benchmarks), an Agent class, or a file.py:function / module:function

agent.concurrency

integer / 4

Maximum concurrent rollout/evaluation task executions; use a positive value

agent.timeout_min

number / null

A sandboxed task call (its worker) running longer is stopped and recorded as an error; null: no limit

agent.params

mapping / {}

Passed to Agent constructors; plain functions receive it when they declare a params argument

agent.base

string / null

Layer 2 in the per-layer form (Agent layers): codex, claude, pi, mini-swe-agent, opencode, dsh, hermes, react, or direct (with agent.name, a task’s own loop); sets agent.name when unset

agent.model

string / mapping / null

Layer 1: a <backend>/<model> reference, or {ref or name, login, effort, price, ...}; read into agent.params

agent.codex, agent.claude, agent.pi, agent.mini-swe-agent, agent.opencode, agent.dsh, agent.hermes, agent.react, agent.direct

mapping / null

Layer 2’s settings for that Base Agent (the one agent.base names); read into agent.params. A key set in two layers is refused

pipeline.run

string / null

Legacy alias for agent.name, applied only when agent.name is unset

pipeline.concurrency

integer / null

Legacy concurrency override when the legacy pipeline alias is used

pipeline.params

mapping / {}

Legacy parameters merged into agent.params when the pipeline alias is used

judge.path

file/module / null; required

Module containing the scoring callable

judge.name

string / score

Callable accepting (task, RunOutput)

Split ids must exist in the task data. Use disjoint train/validation/test splits; check reports overlaps. Task row fields become training material, so private labels require judge-owned storage.

Adapter and learning method#

Field

Type / default

Meaning and constraints

template

string / null; required

Built-in id, id@version, or directory containing .hermit/adapter.yaml

start_from

string / null

Initial adapter tag, commit, or compatible directory; does not restore learner state

evolver.name

string / null; required

Built-in method or directory containing its Evolver definition

evolver.resume

boolean / false

Request learner-session continuation; method must support it

evolver.params

mapping / {}

Overrides merged with the chosen method’s defaults

evolver.base

string / null

Layer 2 the method runs on: codex, claude, pi, opencode, dsh or hermes (an agent Evolver: sets evolver.params.backend) or direct. On a method that calls the run’s model, pi makes that model Pi (llm: {cli: pi, ...})

evolver.model

string / mapping / null

Layer 1, as agent.model; with evolver.base: direct it is the run’s llm

evolver.codex, evolver.claude, evolver.pi, evolver.opencode, evolver.dsh, evolver.hermes, evolver.direct

mapping / null

Layer 2’s settings, read into evolver.params (evolver.pi on a method that calls the run’s model: into llm)

evolver_access.environment

list / []

Granted environment resources; required for MWM’s evidence integration

evolver_access.tools

list / []

Task tool declarations offered to the learner

evolver_access.send_material_out

boolean / false

Consent declaration checked for methods requesting that need; not a network filter

The template defines what is editable. Method selection does not change those rules. See adapter metadata reference for exports, learnable files, and checkers.

Models and backends#

A model is named by a reference, <backend>/<model id>; a backend is an endpoint (base URL, key variable, the dialects it serves, prices). See Model backends.

Field

Type / default

Meaning and constraints

model

string / null

The run’s default model, a <backend>/<model id> reference; used by llm, agent.params.model and the codex, claude, dsh, hermes and mwm Evolvers’ evolver.params.model when they name none

backends

mapping / {}

Backends declared for this run by name, over ~/.config/hermit/backends.yaml and the built-ins. Fields: base_url, api_key_env, key_required, apis, messages_url, litellm, prices, extra_body, context_window, max_output_tokens, models, or from: <other> to copy one

llm

reference, mapping / null

The run’s chat-completions llm tool: a reference, {model: <reference>, price, extra_body}, the endpoint itself (below), or a CLI’s sessions, {cli: ..., ...} (below)

agent.params.model takes the same forms. For a Codex or Claude Code acting agent or Evolver a reference becomes the CLI’s provider settings (args for Codex, env for Claude Code, provider for Pi, OpenCode, DeepSeek Harness and Hermes Agent) and the model’s id; a mini-swe-agent acting agent calls the backend through litellm with the key passed per request. A plain id without a backend goes to the CLI’s own provider as before (for mini-swe-agent: a litellm model id, its key from litellm’s usual variable).

Learner model tool#

llm defaults to null. When configured, it creates the run’s chat-completions tool. It does not configure the acting model in your pipeline or automatically configure an external learner CLI. The endpoint form:

Field inside llm

Type / default

Meaning

base_url

string; required when configured

Endpoint prefix; the client appends /chat/completions

model

string; required when configured

Learner model identifier (or a <backend>/<model id> reference, with no base_url)

api_key_env

string / null

Environment-variable name containing the bearer credential

price

mapping / null

USD per million tokens: input, cached_input, output

extra_body

mapping / {}

Fields added to requests, such as endpoint-specific reasoning settings

Without prices, cost is unknown. With a price mapping, omitted input/output prices default to zero, and omitted cached-input price falls back to the input price. Supply all applicable prices rather than relying on those defaults. Per-call arguments override matching extra_body fields. The underlying client defaults to a 600-second HTTP timeout and four retries; llm.timeout (seconds) is forwarded, llm.max_retries is not.

A model only a CLI reaches, as llm or as an acting pipeline’s agent.model: each chat call is one session with no tools, which on Claude Code or Pi can only reply (Claude subscription). Any other key is the Base Agent’s setting (hermit/agent/base/cli.py).

Field

Type / default

Meaning

cli

codex, claude, pi

The Base Agent. Pi takes a <backend>/<model> reference, isolation: sandbox and no login

model

string

The CLI’s model name; required with login: claude. A <backend>/<model id> reference binds it to that backend’s key instead

login

chatgpt, claude

The user’s subscription on that CLI

isolation

string / sandbox

sandbox: a bubblewrap sandbox of its own (role llm, an acting pipeline’s agent-model: its empty workspace and home, its model’s or login’s hosts through a proxy of its own, its key or token, nothing of the run); container: a Docker container of its own. With sandbox.enabled: false it runs unconfined

container

mapping / {}

With isolation: container: image, network, proxy (else HERMIT_CODEX_* or HERMIT_CLAUDE_*)

web_search

boolean

Required on Codex; on Claude Code false by default, and it cannot be on

effort

string / null

The default reasoning effort; a request’s reasoning_effort overrides it

timeout_s

number / 3600

One session’s clock

timeout

number / 3600

The chat client’s; give it more than timeout_s. With a login the client also waits out the plan: plan_max_wait_s is added (none: no limit)

unapplied

list / []

Request fields accepted without being applied (temperature); others the CLI has no setting for are refused

plan_dir, plan_max_wait_s, plan_rerun, usage_credits

see the guide

The login’s plan. For a workspace session they are the Base Agent’s settings (agent.claude, evolver.claude), not Layer 1’s (agent.model)

Trainer and evaluation#

Field

Type / default

Meaning and constraints

trainer.run_name

string / null

Derived from method/template when null; explicit names use letters/digits, underscores, dots, hyphens, starting alphanumeric, at most 81 characters

trainer.output_dir

path / runs

Parent of the run directory and default adapter-tree directory

trainer.tree_dir

path / null

Overrides default <output_dir>/trees/<template-id>

trainer.epochs

integer / 1

Positive number of training passes

trainer.allow_early_stop

boolean / false

Honor an Evolver’s stop request

trainer.resume_mode

string / auto

Use auto for unfinished-run recovery or disable for a deliberate restart

trainer.save_freq.steps

integer / null

Checkpoint-tag frequency by step; null disables that frequency

trainer.save_freq.epochs

integer / 1

Checkpoint-tag frequency by epoch; null disables that frequency

trainer.budget.usd

number / null

Dollar budget; reliable accounting requires known usage and prices

trainer.budget.tokens

number / null

Token budget

trainer.budget.hours

number / null

Training wall-time budget

trainer.call_timeout_min

number / 60

Per-call timeout in minutes

eval.repeats

integer / 1

Attempts per test task; use a positive value

Use at least one finite budget for a real experiment. Limits are observed at call/rollout boundaries; concurrent work can overshoot. Separate check probes and eval calls are outside the training budget. Checkpoint frequency controls tags; completed steps still have records and accepted adapter history.

Sandboxes#

Field

Type / default

Meaning

environment.runner

string / sandbox

sandbox: the acting agent runs in the task sandbox; host: in the Trainer’s process (a task whose code isolates what it runs)

environment.read

list / []

Task paths shown read-only to the acting agent; never the data, the judge, its tests or the runs

environment.write

list / []

Paths it may write besides its own work directory

environment.packages

list / []

Python distributions shown besides the framework’s environment (an editable install’s package, one on PYTHONPATH), with their dependencies

environment.env

list / []

Variables passed in: names or patterns (MWM_*)

environment.network

string / no-network

no-network, allowlist or public; the agent’s model provider stays reachable

environment.allowed_hosts

list / []

With allowlist: hosts reachable through the proxy

environment.gpu

list / []

NVIDIA GPUs shown in the task sandbox, by the N of /dev/nvidia<N> (CUDA and EGL; inside they count from 0); none: no GPU (EGL renders in software where Mesa is installed). Not with environment.image (sandbox guide)

environment.resources

mapping / {}

memory_mb, file_mb, cpu_s per process (positive whole numbers; null: no limit); not with environment.image (the container keeps its own)

environment.image

string / null

A Docker image: a Codex or Claude Code acting agent runs in a container of its own

environment.container

mapping / {}

With image: the container’s network and proxy

judge.mode

string / host

host, shared or separate

judge.tests

list / []

shared, separate: paths only the judge sees (its own file is shown; a file beside it is not unless listed here)

judge.collect

list / []

separate: paths of the agent’s work directory carried to the judge

sandbox.enabled

boolean / true

False runs everything unconfined

sandbox.enforce

string / required

required or best_effort (run unconfined without bubblewrap, recorded)

sandbox.hide

list / []

Modules or packages of the framework’s environment covered in every sandbox but the judge’s

sandbox.evolver.allowed_hosts

list / []

More hosts the learner reaches, through the proxy

sandbox.evolver.env

list / []

Variables passed to the learner (names or patterns)

sandbox.evolver.resources

mapping / {}

memory_mb, file_mb, cpu_s per process (positive whole numbers; null: no limit)

The backend is Linux/bubblewrap (Docker for environment.image). A sandbox holds its models’ keys, as Harbor’s agents do; what the run keeps is scrubbed of them. An arbitrary in-process Python Evolver’s own code runs in the Trainer; what it starts runs in the learner’s sandbox. Read the boundary description before granting resources.

Complete defaults#

# Framework defaults. A run.yaml and command-line overrides (key.sub=value) change only what they name.
data:
  tasks: null
  train: null
  val: null
  test: null
  step_size: 8
  shuffle: true               # false: every epoch takes the train split in file order (an ordered stream)
  shuffle_seed: 0
task_info: null
agent:
  name: null                  # react | codex | claude-code | pi | mini-swe-agent | opencode | dsh | hermes, or
                              # file.py:Class / file.py:function of the task's own
  concurrency: 4
  timeout_min: null           # a sandboxed task call that runs longer is stopped and recorded as an error; null: none
  params: {}                  # Layer 3: the Acting Agent's own settings (docs/framework/agent-layers.md)
  base: null                  # Layer 2: codex | claude | pi | mini-swe-agent | opencode | dsh | hermes | react |
                              # direct; its settings go in a section of its name
  model: null                 # Layer 1: a <backend>/<model> reference, or {ref | name, login, effort, price, ...}
  codex: null
  claude: null
  pi: null
  mini-swe-agent: null
  opencode: null
  dsh: null
  hermes: null
  react: null
  direct: null
pipeline:                     # the older spelling of `agent`: run -> name
  run: null
  concurrency: null
  params: {}
environment:                   # the task sandbox, where the acting agent runs (rollouts, eval, check)
  runner: sandbox              # sandbox: in the task sandbox | host: in the Trainer's process, for a task whose own
                               # code isolates what it runs (AgentDyn's hooks in containers); warned
  image: null                  # a Docker image: a CLI acting agent runs in a container of its own (Codex or
                               # Claude Code)
  container: {}                # with image: the container's network and egress proxy (hermit/agent/base/container.py)
  packages: []                 # no image: Python distributions shown besides the framework's environment (an editable
                               # install's package, one on PYTHONPATH), with their dependencies
  read: []                     # no image: task paths shown read-only (relative to this file); never the data, the
                               # judge or the runs
  write: []                    # paths the acting agent may write besides its own work directory
  env: []                      # environment variables passed in, names or patterns (MWM_*); the agent's model key
                               # passes anyway; a Claude login's token passes by name to each call
  network: no-network          # no-network | allowlist | public; the agent's model and the tool endpoint stay reachable
  allowed_hosts: []            # allowlist: hosts reachable through the allowlist proxy
  resources: {}                # memory_mb, file_mb, cpu_s: per process
  gpu: []                      # NVIDIA GPUs shown, by the N of /dev/nvidia<N> (CUDA and EGL; inside they count from 0);
                               # none: no GPU (EGL renders in software where Mesa is installed)
judge:
  path: null
  name: score
  mode: host                   # host: on the host, from the answer | shared: in the task sandbox after the agent |
                               # separate: in a fresh judge sandbox holding the collected paths
  tests: []                    # shared, separate: paths only the judge sees, read-only (its answers, test files)
  collect: []                  # separate: paths of the agent's work directory carried to the judge sandbox
template: null
start_from: null
evolver:
  name: null
  resume: false
  params: {}                  # Layer 3: the method's settings
  base: null                  # Layer 2: codex | claude | pi | opencode | dsh | hermes | direct
                              # (the Base Agent the method runs on)
  model: null                 # Layer 1: as agent.model; with direct it is the run's `llm`
  codex: null
  claude: null
  pi: null
  opencode: null
  dsh: null
  hermes: null
  direct: null
evolver_access:
  environment: []
  tools: []
  send_material_out: false
sandbox:                       # docs/developer/sandbox-design.md
  enabled: true                # false: everything the run starts runs unconfined (a warning; not for reported results)
  enforce: required            # required: refuse to run without bubblewrap | best_effort: run unconfined, recorded
  hide: []                     # modules or packages of the framework's environment covered in every sandbox but the
                               # judge's (a benchmark's scoring the agent does not import): `pkg.scoring`
  evolver:                     # the learner's sandbox: a fixed layout under /w, its models, the tool endpoint
    allowed_hosts: []          # more hosts the learner may reach, through the allowlist proxy
    env: []                    # environment variables passed to the learner's sessions (its models' keys pass anyway;
                               # a Claude login's token goes by name with each session on it)
    resources: {}              # memory_mb, file_mb, cpu_s: per process
model: null                    # the run's default model, a `<backend>/<model id>` reference (see backends): what `llm`,
                               # agent.params.model and evolver.params.model use when they name none
backends: {}                   # this run's model backends by name: {base_url, api_key_env, apis, prices, ...} or
                               # {from: <other>, base_url: ...}; over ~/.config/hermit/backends.yaml and the built-ins
llm: null                      # the run's `llm` tool: `<backend>/<model>`, {model: <ref>, extra_body}, or
                               # {base_url, model, api_key_env, price: {input, cached_input, output}, extra_body}
trainer:
  run_name: null
  output_dir: runs
  tree_dir: null               # default: <output_dir>/trees/<template id>
  epochs: 1
  allow_early_stop: false
  resume_mode: auto
  save_freq: {steps: null, epochs: 1}
  budget: {usd: null, tokens: null, hours: null}
  call_timeout_min: 60
eval:
  repeats: 1