Configuration files

Start with the setup wizard and the Web UI’s model controls. Edit configuration files when you need a deliberate, reviewable change—not as a prerequisite for your first conversation.

Read these chapters as three layers of the same setup:

1. Main configuration — services, credentials by reference, environments, storage, model catalog, plugin availability, memory and logging.
2. Model configuration — one model’s identity, capacity, capabilities, generation, context estimation, execution route and calibration overlays.
3. Request-runner configuration — which semantic step uses which settings, context reserves, timeout ownership and reusable instruction files.

For an actual tune-and-retest exercise rather than a reference, follow Model calibration.

The default host combines built-in defaults, your runtime configuration file, and supported environment variables, in that order. Environment variables can therefore override a value you changed in JSON. LLM_RUNTIME_CONFIG_FILE selects a non-default runtime configuration file.

Know which file to change

Configuration	Owns
runtime.config.json	Provider/model catalog, paths, plugin availability, and references to other config files.
A referenced model profile	The concrete provider/model, physical context capacity, execution route, and per-step calibration.
request-runner.config.json	Model-step mappings, timeouts, context headroom, and additional instruction-file references.
.env or the host environment	Secret values and supported deployment overrides.
Plugin packages	Their tool contracts, implementation defaults, secret declarations, and skill bindings.

Do not confuse the four kinds of name

Several fields contain strings that look like model names, but point to different things:

Example name	What it identifies	Where it is defined
ollama-local	A provider connection, including its adapter and endpoint	models.providers.ollama-local in the main file
local-assistant	An ABot model profile, with a provider-model ID and configuration	models.profiles.local-assistant, often using configRef
worker.decision	A runtime step; by default in schema v2 it can also name a calibration slot	Runner step mapping plus the selected model’s calibration
toolPayload.raw	A calibration-slot name; it is deliberately different from the internal tool_payload.raw step ID	The model’s calibration.toolPayload.raw and the runner’s explicit mapping

The actual provider-model ID is the model file’s model value. Renaming local-assistant does not rename or download a model in Ollama. A named environment such as prod is a fifth, unrelated identifier: it chooses the Runtime’s state namespace, not its model.

This distinction helps decode errors. “Unknown provider” is a connection-reference problem. “Unknown model profile” is a catalog-selection problem. A syntactically valid calibration entry that never affects a call is often a step-mapping problem.

Follow one request through the files

For an ordinary request in the default host, think of the process as separate decisions, not one enormous JSON merge:

1. The host loads the main file and resolves the environment and storage paths. Supported process-environment values can override corresponding file values.
2. It loads the model files and the linked request-runner policy. Referenced file paths are resolved from the file that owns that reference.
3. The request’s selected model and effective model policy determine which profile is used. The model’s execution policy chooses the request route; a per-step setting does not turn the whole request into another route.
4. Each model invocation supplies a modelStep. The runner maps it to a concrete profile, invocation profile or semantic calibration slot.
5. The selected configuration supplies the generation/context/format guidance for that call. Applicable per-model calibration and explicit request reasoning settings can affect the effective values.
6. Context admission and timeouts still apply. The provider adapter constructs the actual payload; not every field in ABot’s JSON is forwarded to the provider.

For example, an instructions entry under worker.decision is not global guidance for every message. It only helps when that request reaches the mapped slot on that model. On the Execution Agent route, the main decision step is execution.decision instead. The runner chapter works through selection precedence; the model chapter explains the resulting overlay.

Keep a copy of the files before editing. The snippets below are partial examples to merge into the matching existing objects, not complete replacements for a working installation. Keep other providers, profiles, paths, and required fields intact.

Keep credentials outside JSON

An OpenAI provider references the name of an environment variable, never the key itself:

{
  "models": {
    "providers": {
      "openai": {
        "type": "openai",
        "apiKeyEnv": "OPENAI_API_KEY"
      }
    }
  }
}

Set the actual value in your local .env, service environment, or secret manager. Do not commit that file or paste credentials into a public issue. Provider IDs are identifiers your model profiles reference; keep the reference consistent if you choose a different ID.

Separate execution route from model settings

Inside an existing model profile, this selects the Execution Agent route:

{
  "execution": {
    "policy": "execution-agent-v1"
  }
}

The other registered value is supervisor-worker-v1. Omitting the field uses that Supervisor/Worker policy. This is a choice of model-facing execution contract, not a script describing a fixed sequence. It is resolved once per request, not changed automatically because the model struggles.

Keep contextWindowTokens aligned with the concrete model’s physical capacity. Do not copy a large number from another profile to make a context error disappear. For Ollama, a lower configured options.num_ctx can further constrain the effective allocation. See models and routes for choosing a route.

Add guidance to one step

The runtime config points to a separate request-runner file:

{
  "requestRunner": {
    "configRef": "./request-runner.config.json"
  }
}

That path is relative to the runtime config file. In a request-runner file using schema version 2, additional Markdown guidance can be attached to a specific step:

{
  "schemaVersion": 2,
  "steps": {
    "execution.response": {
      "instructionRefs": ["./methodologies/concise-results.md"]
    }
  }
}

Merge the step into your existing file and preserve any instruction references you still need. Create the referenced file at the path relative to that request-runner file. For example:

Lead with the observed result.
Separate completed actions from suggested next steps.
When a tool failed, explain the limitation instead of claiming success.

This example adds response-writing guidance. It does not grant tools or permissions, replace the runtime’s output contract, or change which actions the role is allowed to take. The Supervisor route’s corresponding response step is supervisor.response; guidance attached only to execution.response does not automatically apply there.

Schema version 2 uses sparse overrides: absent step mappings use the same step ID, and absent per-step timeout entries use stepDefaults.timeoutMs. Preserve required context fields and existing non-identity mappings. Older unversioned request-runner files remain supported; upgrading the package does not automatically rewrite them.

Change one thing, then verify

Retest the same representative task after a change. Inspect model.invocation.resolved to confirm the model/profile and failing modelStep, rather than asking the model which configuration it used. Check actual artifacts and tool results, not only the answer’s wording.

Increasing a timeout can accommodate latency; it does not improve reasoning. Context reserves leave input headroom; outputReserveTokens is not a provider output-token cap. Plugin deny rules take precedence over allow rules, and FULL+ cannot restore an unavailable plugin.

This page explains ownership. Continue with the main-file reference, model-file reference and runner reference for defaults, constraints and worked examples. Keep the published @abot-ai/runtime/runtime.config.schema.json available for editor validation, and use the Field guide for longer calibration examples.