Field-level reference for ~/.apus/apus.json: keys, defaults, and links to deeper subsystem pages. For task-oriented setup guidance, see Configuration. Channel- and plugin-owned command catalogs and deep memory knobs live on their own pages, not here.

Config format is JSON5 (comments + trailing commas allowed). All fields are optional; Apus uses safe defaults when omitted.

Code truth beats this page:

• apus config schema prints the live JSON Schema used for validation and Control UI, with bundled/plugin/channel metadata merged in.
• Agents should call the gateway tool action config.schema.lookup for one exact path-scoped schema node before editing config.
• pnpm config:docs:check / pnpm config:docs:gen validate this doc's baseline hash against the current schema surface.

Schema uiHints also carry a resolved advanced boolean for every path. Control UI uses it to show common fields first and collapse advanced fields per section; search still spans both tiers. Tier metadata is presentational only. When adding a key, declare its tier on the leaf or let it inherit the nearest ancestor declaration. A path with no declared ancestor is advanced by default.

Dedicated deep references:

• Memory configuration reference for memory.search.*, memory.citations, and dreaming config under plugins.entries.memory-core.config.dreaming.
• Slash commands for the current built-in + bundled command catalog.
• Owning channel/plugin pages for channel-specific command surfaces.

Pages in this reference set

• Configuration — runtime basics — runtime config: worktree root, model routing, discovery, updates, ACP, and the wizard.
• Configuration — MCP, skills, and plugins — extension config: MCP servers, skills, plugin entries, and the canvas widget presenter.
• Configuration — browser, UI, and desktop — browser automation, Control UI presentation, and desktop or paired-node config.
• Configuration — gateway — gateway config: bind, auth, roles, Control UI, terminal, remote, nodes, TLS, and reload.
• Configuration — cloud worker environments — cloud worker profiles under cloudWorkers, including Crabbox and static SSH development.
• Storage locations — named storage destinations under storage.locations, initialization, and encryption.
• Configuration — hooks — hook config: HTTP contract, agent payload, session policy, mapping, retries, and Gmail.
• Configuration — environment, secrets, and includes — environment variables, secret providers, auth storage, and $include config splitting.
• Configuration — audit, logging, diagnostics, and telemetry — observability config: audit, logging, diagnostics, and telemetry keys.
• Configuration — automations and media template variables — automation config under cron plus the media model template variable surface.
• Configuration — agents — agent defaults, multi-agent routing, sessions, messages, and talk.
• Configuration — channels — per-channel access control, pairing, and channel keys.
• Configuration — tools — tool enablement and custom tool providers.

Channels

Per-channel config keys live in Configuration - channels: channels.* for Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, and other channel plugins (auth, access control, multi-account, mention gating).

Agent defaults, multi-agent, sessions, and messages

See Configuration - agents for:

• agents.defaults.* (workspace, model, thinking, heartbeat, memory, media, skills, sandbox)
• multiAgent.* (multi-agent routing and bindings)
• session.* (session lifecycle, compaction, pruning)
• messages.* (message delivery, TTS, markdown rendering)
• talk.* (Talk mode)
  • talk.consultThinkingLevel: thinking level override for the full Apus agent run behind Control UI Talk realtime consults
  • talk.consultFastMode: one-shot fast-mode override for Control UI Talk realtime consults
  • talk.speechLocale: optional BCP 47 locale id for Talk speech recognition on Android, iOS, and macOS, and for iOS system-voice fallback
  • talk.silenceTimeoutMs: when unset, Talk keeps the platform default pause window before sending the transcript (700 ms on macOS and Android, 900 ms on iOS)
  • talk.realtime.consultRouting: Gateway relay fallback for finalized realtime Talk transcripts that skip apus_agent_consult

worktreeRoot

Worktree storage (worktreeRoot), filesystem acceleration (worktreeAcceleration), and the live-checkout cap (worktreeMaxCount) are documented in Configuration — runtime basics.

Tools and custom providers

Tool policy, experimental toggles, provider-backed tool config, and custom provider / base-URL setup live in Configuration - tools and custom providers.

agents.entries.<id>.tools.github.allowInSandbox is an optional boolean, defaulting to false. Set it on an agent's managed GitHub identity to expose that identity to the agent's own Docker or Podman sandbox, including a role-required sandbox. The profile is mounted read-only at /apus/github; effective shared scope refuses injection. This setting is not accepted under global tools.github, and security audit warns for every opted-in agent. See GitHub identity for setup, credential exposure, and backend requirements.

Models

Moved to Configuration — runtime basics.

MCP

Moved to Configuration — MCP, skills, and plugins.

Skills

Moved to Configuration — MCP, skills, and plugins.

Plugins

Moved to Configuration — MCP, skills, and plugins. Sections: Codex harness plugin config.

Browser

Moved to Configuration — browser, UI, and desktop.

UI

Moved to Configuration — browser, UI, and desktop.

Desktop

Moved to Configuration — browser, UI, and desktop. Sections: Paired node desktops.

Gateway

Moved to Configuration — gateway. Sections: OpenAI-compatible endpoints, Multi-instance isolation, gateway.tls, gateway.reload.

Cloud worker environments

Moved to Configuration — cloud worker environments. Sections: Crabbox profile, Static SSH development profile.

Hooks

Moved to Configuration — hooks. Sections: Hook HTTP contract, Hook agent payload, Hook session and agent policy, Mapping details, Hook retries and fan-out, Gmail integration.

Canvas widget presenter

Moved to Configuration — MCP, skills, and plugins.

Discovery

Moved to Configuration — runtime basics. Sections: mDNS (Bonjour), Wide-area (DNS-SD).

Environment

Moved to Configuration — environment, secrets, and includes. Sections: env (inline env vars), Env var substitution.

Secrets

Moved to Configuration — environment, secrets, and includes. Sections: secrets.egressProxy, SecretRef, Supported credential surface, Secret providers config.

Auth storage

Moved to Configuration — environment, secrets, and includes.

Audit

Moved to Configuration — audit, logging, diagnostics, and telemetry.

Logging

Moved to Configuration — audit, logging, diagnostics, and telemetry.

Diagnostics

Moved to Configuration — audit, logging, diagnostics, and telemetry.

Telemetry

Moved to Configuration — audit, logging, diagnostics, and telemetry.

Update

Moved to Configuration — runtime basics.

ACP

Moved to Configuration — runtime basics.

Wizard

Moved to Configuration — runtime basics.

Identity

See agents.entries identity fields under Agent defaults.

Bridge (legacy, removed)

Moved to Configuration — runtime basics.

Automations (cron)

Moved to Configuration — automations and media template variables. Sections: cron.failureAlert.

Media model template variables

Moved to Configuration — automations and media template variables.

Config includes ($include)

Moved to Configuration — environment, secrets, and includes.

Related

• Configuration
• Configuration examples
• Doctor
• Cloud Workers — the feature these worker settings configure
• apus configure — interactive prompts that edit these settings without hand-editing the file