Configuration Reference
September 8, 2026 · View on GitHub
Generated from packages/harness/src/config/domain.ts and the domain-owned configuration schemas composed by packages/product-runtime/src/configuration.ts. Concept and layout guidance lives in Configuration layout.
Domains
| Domain | File | Merge policy |
|---|---|---|
general | 00-general.jsonc | merge |
models | 10-models.jsonc | merge |
providers | 20-providers.jsonc | merge |
library | 30-library.jsonc | merge |
mcp | 40-mcp.jsonc | merge |
plugins | 50-plugins.jsonc | merge |
skills | 55-skills.jsonc | merge |
agents | 60-agents.jsonc | merge |
commands | 70-commands.jsonc | merge |
permissions | 80-permissions.jsonc | merge |
channels | 90-channels.jsonc | merge |
holos | 100-holos.jsonc | merge |
email | 110-email.jsonc | merge |
github | 115-github.jsonc | merge |
runtime | 120-runtime.jsonc | merge |
voice | 125-voice.jsonc | merge |
General
File: 00-general.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
$schema | string (optional) | JSON schema reference for configuration validation |
logLevel | Log.Level.optional (optional) | Log level |
snapshot | boolean (optional) | |
username | string (optional) | Custom username to display in conversations instead of system username |
embedding | EmbeddingConfig | |
rerank | RerankConfig | |
theme | string (optional) | Theme name to use for the interface |
keybinds | Keybinds.optional (optional) | Custom keybind configurations |
toast | "info" | "success" | "warning" | "error" (optional) | Toast notification preferences |
compactReasoning | boolean (optional) | Show live reasoning in a compact single-line viewport |
locale | "system" | "en" | "zh-CN" (optional) | UI locale (system = follow OS, default: system) |
activityDisplay | "full" | "balanced" | "minimal" (optional) | How much activity detail to show in the interface: full = everything, balanced = semantic activity grouping, minimal = only essential activity (default: balanced) |
defaultSessionWorkspace | "main" | "worktree" (optional) | Default workspace for new sessions started from the Web composer: main = run in the main checkout, worktree = start each new session in an isolated git worktree (default: main). Programmatic session creation (API, channels, Cortex) always uses the main checkout. |
layout | Layout.optional (optional) | @deprecated Always uses stretch layout. |
Models
File: 10-models.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
model | string (optional) | Default model in the format of provider/model, eg anthropic/claude-sonnet-4-5 |
nano_model | string (optional) | Cheapest model for trivial extraction tasks like title generation, in the format of provider/model. Falls back to mini_model → mid_model → model. |
mini_model | string (optional) | Lightweight model for simple tasks like intent extraction, in the format of provider/model. Falls back to mid_model → model. |
mid_model | string (optional) | Mid-tier model for internal agents that need moderate reasoning (script extraction, reward evaluation, code exploration), in the format of provider/model. Falls back to the default model. |
thinking_model | string (optional) | Deep thinking model for complex reasoning and architecture tasks, in the format of provider/model. Falls back to the default model if not set. |
long_context_model | string (optional) | Model with extra-large context window for processing very long inputs, in the format of provider/model. Falls back to the default model if not set. |
creative_model | string (optional) | Model for creative and visual tasks (UI design, writing, artistry), in the format of provider/model. Falls back to the default model if not set. |
vision_model | string (optional) | Model for separate image analysis via the look_at tool, in the format of provider/model. If not set, look_at is disabled. Direct current-model image context uses view_image based on the active model capability. |
role_variant | string (optional) | Default variant (e.g. low, medium, high, xhigh) applied per model role. Requires the resolved model to support the named variant. |
quick_switcher | QuickSwitcher.optional (optional) | Quick switcher model visibility preferences |
Providers
File: 20-providers.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
provider | string (optional) | Custom provider configurations and model overrides |
enabled_providers | string (optional) | When non-empty, ONLY these providers will be enabled. Empty arrays are ignored in each config layer, preserving lower-priority filters |
disabled_providers | string (optional) | Disable providers that are loaded automatically. Empty arrays are ignored in each config layer, preserving lower-priority filters |
Library
File: 30-library.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
library | LibraryConfig |
MCP
File: 40-mcp.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
mcp | object (optional) | MCP (Model Context Protocol) server configurations |
mcpDefaults | McpDefaults.optional (optional) | Default settings applied to all MCP servers that don't override them |
Plugins
File: 50-plugins.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
plugin | string (optional) | |
pluginConfig | string (optional) | Per-plugin configuration namespaces. Keys are plugin IDs, values are plugin-specific config. |
pluginRuntimePolicy | PluginRuntimePolicy.optional (optional) | Plugin runtime isolation policy configuration |
pluginMarketplace | PluginMarketplace.optional (optional) | Public plugin marketplace registry configuration |
Skills
File: 55-skills.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
skills | SkillsConfig |
Agents
File: 60-agents.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
default_agent | string (optional) | Default agent to use when none is specified. Must be a primary agent. Falls back to 'synergy' if not set or if the specified agent is invalid. |
agent | object (optional) | Agent configuration |
instructions | string (optional) | Additional instruction files or patterns to include |
project_doc_fallback_filenames | string (optional) | Ordered fallback instruction filenames to try when AGENTS.md is missing in a directory |
project_doc_max_bytes | number (optional) | Maximum bytes to include from each automatically discovered instruction file (default: 32768; 0 disables automatic discovery) |
category | string (optional) | Custom category configurations for background tasks. Categories define model and prompt presets. |
prompt | object (optional) | Include the git coauthor reminder in agent prompts (default: true) |
external_agent | string (optional) | External agent configurations (e.g. codex, claude-code) |
Commands
File: 70-commands.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
command | string (optional) |
Permissions
File: 80-permissions.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
permission | Permission.optional (optional) | |
tools | string (optional) | |
controlProfile | ControlProfileId.optional (optional) | Default control profile applied to all agents |
sandbox | SandboxConfig.optional (optional) | Sandbox configuration for workspace boundary enforcement |
smartAllow | boolean (optional) | Use the SmartAllow internal agent to auto-allow high-confidence safe asks in guarded mode and eligible false-positive denies in autonomous mode using metadata or redacted evidence only; full_access does not need SmartAllow |
Channels
File: 90-channels.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
channel | string (optional) | Channel configurations for messaging platform integrations |
Holos
File: 100-holos.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
holos | Holos.optional (optional) | Holos platform configuration |
enterprise | object (optional) | Enterprise URL |
File: 110-email.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
email | Email.optional (optional) | Outgoing email configuration |
GitHub
File: 115-github.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
github | Github.optional (optional) | GitHub integration settings (git identity sync, agenda watch) |
Runtime
File: 120-runtime.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
server | Server.optional (optional) | Server configuration for synergy serve and web commands |
timeout | number (optional) | Seconds before unanswered questions auto-expire (0 = no timeout, default 3600 = 1h) |
cortex | object (optional) | Cortex task scheduling configuration |
execution | object (optional) | Time an excess idle Agent worker remains warm before retirement (default: 60000) |
watcher | object (optional) | |
question | object (optional) | Seconds before unanswered questions auto-expire (0 = no timeout, default 3600 = 1h) |
compaction | object (optional) | Enable Codex Remote Compaction V2 for openai-codex sessions: request an opaque server-side compaction artifact alongside the local text summary and replay it on later same-model turns (default: false). |
observability | ObservabilityConfig.optional (optional) | Local logs, indexed telemetry, and diagnostics settings |
formatter | object (optional) | |
lsp | boolean (optional) | Expose the LSP tool; permission checks still apply (default: false) |
lspWriteDiagnostics | boolean (optional) | Include LSP diagnostics after file-writing tools complete (default: true) |
lspDiagnostics | "error" | "warning" (optional) | Severity and scope policy for diagnostics returned after file-writing tools |
toolExposure | object (optional) | Expose the LSP tool; permission checks still apply (default: false) |
boss | object (optional) | Re-inject the versioned world-overview briefing every N days (default: disabled) |
Voice
File: 125-voice.jsonc · Merge: merge
| Key | Type | Description |
|---|---|---|
voice | VoiceConfig |