---
title: "CONFIG-SCHEMA.md Template"
summary: "Agent quick reference for symi config set dotpaths"
read_when:
  - Agent needs to modify its own configuration
  - Agent is asked to set API keys, change models, or adjust settings
---

# Symi Configuration Schema — Agent Quick Reference

Use `symi config set <dotpath> <value>` to modify configuration.
Use `symi config get <prefix>` to discover available paths under a prefix.
Use `symi config get` (no args) to see all top-level keys.

**After changes:** The gateway auto-reloads config (hybrid mode). If it doesn't, send SIGUSR1: `kill -USR1 $(pgrep -f 'symi gateway')`

**Never guess paths.** If unsure, run `symi config get <prefix>` to discover valid keys.

---

## Model Selection

| Path                                 | Type     | Example                         |
| ------------------------------------ | -------- | ------------------------------- |
| `agents.defaults.model.primary`      | string   | `"anthropic/claude-sonnet-4-6"` |
| `agents.defaults.model.fallbacks`    | string[] | `["redsand/gemma-4-31b"]`       |
| `agents.defaults.imageModel.primary` | string   | `"anthropic/claude-sonnet-4-6"` |

## API Keys & Web Search

| Path                                 | Type    | Example                             |
| ------------------------------------ | ------- | ----------------------------------- |
| `tools.web.search.enabled`           | boolean | `true`                              |
| `tools.web.search.provider`          | string  | `"brave"`, `"perplexity"`, `"grok"` |
| `tools.web.search.apiKey`            | string  | `"BSA_xxx"` (Brave Search)          |
| `tools.web.search.maxResults`        | number  | `5`                                 |
| `tools.web.search.perplexity.apiKey` | string  | Perplexity-specific key             |
| `tools.web.search.grok.apiKey`       | string  | Grok/xAI key                        |
| `tools.web.fetch.enabled`            | boolean | `true`                              |
| `tools.web.fetch.firecrawl.apiKey`   | string  | Firecrawl API key                   |

## Sampling & Model Overrides

| Path                                                      | Type    | Example |
| --------------------------------------------------------- | ------- | ------- |
| `agents.defaults.models["provider/model"].streaming`      | boolean | `true`  |
| `agents.defaults.models["provider/model"].timeoutSeconds` | number  | `120`   |
| `agents.defaults.timeoutSeconds`                          | number  | `120`   |

## Agent Behavior

| Path                                | Type          | Example                       |
| ----------------------------------- | ------------- | ----------------------------- |
| `agents.defaults.planModeThreshold` | number (1-20) | `8`                           |
| `agents.defaults.verboseDefault`    | string        | `"off"`, `"on"`, `"full"`     |
| `agents.defaults.thinkingDefault`   | string        | `"off"`, `"medium"`, `"high"` |
| `agents.defaults.promptMode`        | string        | `"full"`, `"coding"`          |

## Sub-agents

| Path                                            | Type          | Example                         |
| ----------------------------------------------- | ------------- | ------------------------------- |
| `agents.defaults.subagents.maxConcurrent`       | number        | `4`                             |
| `agents.defaults.subagents.maxSpawnDepth`       | number (1-5)  | `3`                             |
| `agents.defaults.subagents.maxChildrenPerAgent` | number (1-20) | `5`                             |
| `agents.defaults.subagents.model`               | string        | `"anthropic/claude-sonnet-4-6"` |

## Memory & Context

| Path                                    | Type    | Example                            |
| --------------------------------------- | ------- | ---------------------------------- |
| `agents.defaults.memorySearch.enabled`  | boolean | `true`                             |
| `agents.defaults.memorySearch.provider` | string  | `"openai"`, `"ollama"`, `"voyage"` |
| `agents.defaults.memorySearch.model`    | string  | `"nomic-embed-text"`               |
| `agents.defaults.contextTokens`         | number  | `131072`                           |
| `memory.backend`                        | string  | `"builtin"`, `"qmd"`               |
| `memory.citations`                      | string  | `"auto"`, `"on"`, `"off"`          |

## Tool Access Control

| Path                    | Type     | Example                                          |
| ----------------------- | -------- | ------------------------------------------------ |
| `tools.profile`         | string   | `"minimal"`, `"coding"`, `"messaging"`, `"full"` |
| `tools.allow`           | string[] | `["exec", "web_search"]`                         |
| `tools.deny`            | string[] | `["browser_navigate"]`                           |
| `tools.alsoAllow`       | string[] | `["memory_search"]`                              |
| `tools.exec.security`   | string   | `"deny"`, `"allowlist"`, `"full"`                |
| `tools.exec.timeoutSec` | number   | `30`                                             |

## Gateway

| Path                        | Type    | Example                                   |
| --------------------------- | ------- | ----------------------------------------- |
| `gateway.port`              | number  | `18789`                                   |
| `gateway.mode`              | string  | `"local"`, `"remote"`                     |
| `gateway.bind`              | string  | `"loopback"`, `"lan"`, `"auto"`           |
| `gateway.auth.mode`         | string  | `"none"`, `"token"`, `"password"`         |
| `gateway.auth.token`        | string  | `"..."`                                   |
| `gateway.reload.mode`       | string  | `"hybrid"`, `"hot"`, `"restart"`, `"off"` |
| `gateway.reload.debounceMs` | number  | `300`                                     |
| `gateway.controlUi.enabled` | boolean | `true`                                    |

## Logging

| Path                   | Type   | Example                           |
| ---------------------- | ------ | --------------------------------- |
| `logging.level`        | string | `"info"`, `"debug"`, `"warn"`     |
| `logging.consoleLevel` | string | `"info"`                          |
| `logging.consoleStyle` | string | `"pretty"`, `"compact"`, `"json"` |

## Model Profiles (v2.3.0+)

| Path                              | Type   | Example                              |
| --------------------------------- | ------ | ------------------------------------ |
| `models.profiles`                 | array  | User-defined model profile overrides |
| `models.providers.<name>.baseUrl` | string | `"https://..."`                      |
| `models.providers.<name>.apiKey`  | string | API key                              |
| `models.providers.<name>.api`     | string | `"openai-completions"`, `"ollama"`   |

---

## Discovery Commands

```bash
# Show all top-level config keys
symi config get

# Show all model-related config
symi config get models

# Show all tool config
symi config get tools

# Show current model
symi config get agents.defaults.model

# Show web search config
symi config get tools.web.search

# Show gateway config
symi config get gateway

# Validate config
symi doctor
```

## Common Tasks

```bash
# Set Brave Search API key
symi config set tools.web.search.apiKey "BSA_xxx"
symi config set tools.web.search.provider brave
symi config set tools.web.search.enabled true

# Switch primary model
symi config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

# Change gateway port
symi config set gateway.port 18790

# Enable verbose tool output
symi config set agents.defaults.verboseDefault "on"

# Adjust plan mode threshold
symi config set agents.defaults.planModeThreshold 12
```
