Apus reads an optional JSON5 config from ~/.apus/apus.json. If the file is missing, Apus uses safe defaults.

The active config path must be a regular file. Apus-owned writes replace it atomically (rename onto the path), so a symlinked apus.json gets its target replaced rather than written through - avoid symlinked config layouts. If you keep config outside the default state directory, point APUS_CONFIG_PATH directly at the real file.

Common reasons to add a config:

See the Configuration reference for every available field.

Configuration follows a two-bucket rule: root siblings hold infrastructure and cross-agent defaults, while agents.defaults holds agent-loop behavior. Entries under agents.entries may override either bucket where the schema supports a per-agent override.

Agents and automation should use config.schema.lookup for exact field-level docs before editing config. Use this page for task-oriented guidance and Configuration reference for the broader field map and defaults.

New to configuration? Start with apus onboard for interactive setup, or check out the Configuration Examples guide for complete copy-paste configs.

Minimal config

// ~/.apus/apus.json
{
  agents: { defaults: { workspace: "~/.apus/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Editing config

Interactive wizard

```bash
apus onboard       # full onboarding flow
apus configure     # config wizard
```

CLI (one-liners)

```bash
apus config get agents.defaults.workspace
apus config set agents.defaults.heartbeat.every "2h"
apus config unset plugins.entries.brave.config.webSearch.apiKey
```

Control UI

Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Config** tab.
The Control UI renders a form from the live config schema, including field
`title` / `description` docs metadata plus plugin and channel schemas when
available, with a **Raw JSON** editor as an escape hatch. For drill-down
UIs and other tooling, the gateway also exposes `config.schema.lookup` to
fetch one path-scoped schema node plus immediate child summaries.
Settings show common fields first. Each section keeps its advanced fields
in a collapsed **Advanced (N)** group. Use **Show advanced** to expand all
groups. Settings search always includes both tiers and opens the matching
advanced group when needed. Per-channel settings under **Settings ->
Channels** use the same split and share the **Show advanced** preference,
with **Hide advanced** on the divider to collapse them again.

Direct edit

Edit `~/.apus/apus.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](/gateway/configuration/hot-reload)).

Strict validation

Apus only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start. Run apus doctor --fix to repair legacy keys before starting the Gateway. The only root-level exception is $schema (string), so editors can attach JSON Schema metadata.

apus config schema prints the canonical JSON Schema used by Control UI and validation. config.schema.lookup fetches a single path-scoped node plus child summaries for drill-down tooling. Field title/description docs metadata carries through nested objects, wildcard (*), array-item ([]), and anyOf/ oneOf/allOf branches. Runtime plugin and channel schemas merge in when the manifest registry is loaded.

Every config leaf has a common or advanced presentation tier in uiHints. advanced: false marks common settings and advanced: true marks advanced settings. A leaf inherits the nearest ancestor tier when it has no direct hint. Paths with no declared ancestor default to advanced. This affects presentation only, not validation, defaults, reload behavior, or whether the key can be set.

Startup migration uses the same deterministic, prompt-free transforms as apus doctor --fix and writes only when the entire migrated config validates, including plugins. The previous config stays in the .bak ring. Configs using $include, Nix-managed configs, and configs written by a newer Apus version are not automatically migrated. See Legacy config key migrations for the conditions and fallback.

When validation still fails:

The Gateway keeps a trusted last-known-good copy after each successful startup, but startup and hot reload do not restore it automatically - only apus doctor --fix does. If apus.json remains invalid after eligible startup migrations (including plugin-local validation), Gateway startup fails. An invalid hot reload is skipped and the current runtime keeps the last accepted config. When a write is blocked as an accidental clobber, Apus attempts to save the rejected payload as <path>.rejected.<timestamp> for inspection. The warning reports whether that save succeeded. If it failed, the active config still stays unchanged. The Gateway blocks writes that look like accidental clobbers - dropping the effective gateway.mode or shrinking the file by more than half - unless the write explicitly allows destructive changes. Mode checks resolve $include and environment references first. Missing meta is recorded as a write anomaly. Promotion to last-known-good is skipped when a candidate contains a redacted secret placeholder such as *** or [redacted].

Configuration pages

This page is an index. The longer reference sections live on four pages. Open the page that matches what you need.

Page Read it when
Common tasks You want a copy-paste recipe for a channel, model, access rule, session, or automation.
Config hot reload An edit did not take effect, or you need to know what forces a Gateway restart.
Config RPC Tooling writes config over the gateway API instead of editing the file.
Environment variables You are deciding where an API key lives, or using ${VAR} substitution or secret refs.

Where each section moved

Every anchor this page used to publish is kept here, so an existing link such as /gateway/configuration#config-hot-reload still resolves. Each entry points at the page that now holds the content.

Full reference

For the complete field-by-field reference, see Configuration reference.

Related: Configuration Examples · Configuration reference · Doctor

Related