# Config file reference Every setting `~/.jazz/config.json` (or a project's `./.jazz/config.json`) accepts. The table is generated from the schema Jazz validates config files against, so a key missing here is a key Jazz rejects: `jazz config validate` names it and suggests the closest real one. - **Key** is the dotted path `jazz config get` and `jazz config set` take. ``, ``, `` and `
` stand for a name you choose or a member of a family; `[]` marks a list whose entries each have these fields. - **Accepts** is what the value must be, in the words `jazz config validate` uses. - **Secret** keys belong in the keyring. `jazz config set` stores them there when one is available, and falls back to the protected secrets file otherwise. Environment variables for the same secrets are listed in [Environment variables](./environment-variables.md). [Jazz configuration](./jazz.md) explains how global and project files merge, and the [agent file](./agents.md) has its own keys. | Key | Accepts | Secret | What it does | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `storage.type` | file or database | | Storage backend. `file` is the only one Jazz implements. | | `storage.path` | text | | Data directory for `file` storage. Defaults to the Jazz home (`~/.jazz`). | | `storage.connectionString` | text | | Connection string for `database` storage, which Jazz does not implement. | | `logging.level` | debug, info, warn, or error | | Lowest level written to the log files. Defaults to `info`; `--debug` sets `debug`. | | `logging.format` | json or plain | | Log line format. Defaults to `plain`; `json` writes one object per line. | | `logging.retentionDays` | a whole number greater than 0 | | Days log files are kept after their last write. Defaults to 14; one-shot firing logs are kept for one day. | | `logging.maxTotalSizeMB` | a whole number greater than 0 | | Size cap for the logs directory in megabytes. Oldest files are removed first. Defaults to 200. | | `llm.streamIdleTimeoutMs` | a whole number greater than 0 | | How long a model stream may stay silent before Jazz abandons it, in milliseconds. Defaults to 120000. | | `llm.capabilityOverrides...reasoning.kind` | unsupported, toggle, effort, manual, adaptive, or budget | | Which reasoning control the model accepts. See [Model providers](./providers.md#model-capability-overrides). | | `llm.capabilityOverrides...reasoning.transport` | ollama.chat.think, openai-compatible.chat.template-enable-thinking, openai.responses.reasoning-effort, openai-compatible.chat.reasoning-effort, anthropic.messages.extended-thinking, anthropic.messages.adaptive-thinking, or openai-compatible.chat.template-thinking-budget | | The request field that carries the reasoning control. Each `kind` accepts its own transports. | | `llm.capabilityOverrides...reasoning.canDisableReasoning` | true or false | | Whether the model accepts reasoning turned off. | | `llm.capabilityOverrides...reasoning.efforts` | a list | | Effort levels the model accepts, for `effort`, `adaptive` and `manual`. | | `llm.capabilityOverrides...reasoning.minimumBudgetTokens` | a whole number greater than 0 | | Smallest thinking budget the model accepts, for `manual` and `budget`. | | `llm.capabilityOverrides...reasoning.maximumBudgetTokens` | a whole number greater than 0 | | Largest thinking budget the model accepts, for `manual` and `budget`. | | `llm.capabilityOverrides...supportsTools` | true or false | | Whether the model can call tools, overriding the model catalog. | | `llm..api_key` | text | yes | API key for the provider, kept in the keyring when one is available. The provider's environment variable also works. See [Model providers](./providers.md). Applies to every provider except `chatgpt`. | | `llm.anthropic.workspace_id` | text | | Anthropic workspace, needed alongside a key tied to a Console user rather than a workspace. | | `llm.chatgpt.account_id` | text | | Account of the ChatGPT sign-in. Written by Jazz when you sign in. | | `llm.chatgpt.plan` | text | | Plan of the ChatGPT sign-in, such as `plus` or `pro`. Written by Jazz. | | `llm..base_url` | text | | Server address of a self-hosted provider. Applies to `llamacpp`, `ollama`, `sglang`, `vllm`. | | `llm.ollama.keep_alive` | text | | How long Ollama keeps the model loaded, such as `30m`, or `-1` to keep it resident. | | `web_search..api_key` | text | yes | API key for the web search provider. | | `web_search.provider` | exa, parallel, tavily, brave, perplexity, linkup, or treg | | Web search provider agents use when an agent does not name one. | | `network.allowPrivateHosts` | a list | | Hosts on this machine or your local network agents may reach without asking: hostnames, `*.suffix` wildcards, IP addresses or CIDR blocks, at most 64. Any other private address asks for approval, and approving adds it here. Read from the global config only. See [Private network hosts](./jazz.md#private-network-hosts). | | `network.httpApproval` | allow or a list | | HTTP requests and web fetches run automatically by default, including private destinations and after untrusted content. Set a URL array to approve only matching requests automatically; every other request asks or parks. Exact HTTP(S) URLs include query strings; trailing /* grants a path prefix on the same origin. A one-call approval never changes the list. The browser tools load only matching URLs. Global config only. | | `browser.headless` | true or false | | Run a launched browser headless by default; set false for a visible window to watch the run. | | `browser.endpoint` | an http(s):// or ws(s):// DevTools URL | | A running browser the browser tools drive: an `http(s)://` or `ws(s)://` DevTools URL. Without it, the tools try a browser you run on the local DevTools port (`http://127.0.0.1:9222`), then a launched Chrome. Page content and typed text reach the browser's host. Global config only. See [Browser Use](../concepts/browser-use.md). | | `output.showReasoning` | true or false | | Show the model's reasoning. Defaults to true. | | `output.showToolExecution` | true or false | | Show each tool call as it runs. Defaults to true. | | `output.collapseReasoning` | true or false | | Collapse finished reasoning to one line; Ctrl+R expands it. Defaults to true. | | `output.mode` | rendered, hybrid, raw, or quiet | | Terminal output style. Defaults to `hybrid`; `quiet` suppresses output for background runs. | | `output.colorProfile` | full, basic, or none | | Color depth: `full`, `basic` (16 colors, no emoji) or `none`. Detected from the terminal when unset. | | `output.showMetrics` | true or false | | Show first-token latency, tokens per second and duration after each answer. Defaults to true. | | `output.streaming.enabled` | true, false, or auto | | Stream answers as they arrive. Defaults to `auto`, which streams on a terminal. | | `output.streaming.textBufferMs` | a whole number of 0 or more | | How long streamed text is batched before it is drawn, in milliseconds. Defaults to 50. | | `mcpServers..enabled` | true or false | | Turn a server defined in `.agents/mcp.json` on or off. | | `mcpServers..trusted` | true or false | | Let the server's tool annotations set their risk level. See [MCP](./mcp.md). | | `notifications.enabled` | true or false | | Send desktop notifications for completions and approvals. | | `notifications.sound` | true or false | | Play a sound with desktop notifications. | | `notifications.terminal` | auto, osc99, osc777, osc9, or off | | How desktop notifications reach a terminal that shows them itself: `auto` detects kitty, Ghostty, WezTerm, Warp and iTerm2; `osc99`, `osc777` or `osc9` forces that escape sequence (for example over SSH); `off` always uses the system notifier. `JAZZ_NOTIFICATIONS_TERMINAL` wins. Defaults to `auto`. See [Desktop notifications](./notifications.md#desktop-notifications). | | `autoApprovedCommands` | a list | | Shell commands approved without asking. See [Approvals](../security/approvals.md). | | `telemetry.enabled` | true or false | | Record local telemetry. Defaults to true. | | `telemetry.storagePath` | text | | Directory for local telemetry. Defaults to `telemetry` in the Jazz home. | | `telemetry.bufferSize` | a whole number of 0 or more | | Events held in memory before a flush. Defaults to 100. | | `telemetry.flushIntervalMs` | a whole number of 0 or more | | Time between automatic flushes, in milliseconds. Defaults to 30000. | | `telemetry.retentionDays` | a whole number of 0 or more | | Days local telemetry is kept. Defaults to 90. | | `telemetry.otlp.enabled` | true or false | | Set to false to stop OTLP export while keeping the endpoint configured. Export is on whenever an endpoint is set. | | `telemetry.otlp.signals` | a list | | Signals to export. Defaults to `traces`; add `logs` or `metrics`. | | `telemetry.otlp.endpoint` | text | | Collector base URL, such as `http://localhost:4318`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`. | | `telemetry.otlp.tracesEndpoint` | text | | Full traces URL, overriding `endpoint`. | | `telemetry.otlp.logsEndpoint` | text | | Full logs URL, overriding `endpoint`. | | `telemetry.otlp.metricsEndpoint` | text | | Full metrics URL, overriding `endpoint`. | | `telemetry.otlp.headers.
` | text | yes | An HTTP header sent with every export, typically auth. Every header is stored as a secret. | | `telemetry.otlp.serviceName` | text | | `service.name` on exported records. Defaults to `jazz`. | | `telemetry.otlp.resourceAttributes.` | text | | A resource attribute on every exported record, such as `deployment.environment`. | | `telemetry.otlp.timeoutMs` | a whole number of 0 or more | | Per-request export timeout, in milliseconds. Defaults to 10000. | | `telemetry.otlp.maxQueuedBytes` | a whole number greater than 0 | | Disk space for pending traces and logs. Defaults to 32 MiB. | | `telemetry.otlp.maxQueueAgeMs` | a whole number greater than 0 | | Age at which pending traces and logs are dropped, in milliseconds. Defaults to seven days. | | `telemetry.otlp.metricExportIntervalMs` | a whole number greater than 0 | | Time between metric exports, in milliseconds. Defaults to 30000. | | `maxRetries` | a whole number of 0 or more | | Retries for a transient model API failure. Defaults to 10. | | `editor` | text | | Editor for `jazz persona edit` and `jazz mcp add`, such as `code --wait`. Defaults to `$VISUAL`, then `$EDITOR`, then `vi`. | | `maxSubagentDepth` | a whole number of 0 or more | | How many levels of sub-agents may nest. Defaults to 3; 0 turns delegation off. | | `maxLiveSubagents` | a whole number greater than 0 | | Sub-agents running at once in a run, or in a chat across its turns. Defaults to 10. | | `maxIterations` | a whole number of 0 or more, where 0 means unlimited | | Model rounds per top-level run. 0 = unlimited. Unset: unlimited in a terminal, 100 when unattended; `--max-iterations` wins. A user-visible warning fires at 50/70/90% of the cap. | | `maxSubagentIterations` | a whole number of 0 or more, where 0 means unlimited | | Model rounds per sub-agent run. 0 = unlimited. Unset: unlimited under an attended run, 30 when unattended; `--max-subagent-iterations` wins. | | `maxCostUSD` | a number greater than 0 | | Spend ceiling per run, in US dollars. Unset means no ceiling; `--max-cost-usd` wins. See [Budgets](../concepts/budgets.md). | | `maxTokens` | a whole number greater than 0 | | Token ceiling per run. Unset means no ceiling; `--max-tokens` wins. | | `maxDurationMs` | a whole number greater than 0 | | Wall-clock ceiling per run, in milliseconds. Unset means no ceiling; `--max-duration-ms` wins. | | `context.warnThresholdRatio` | a number greater than 0 and less than 1 | | Share of the context window at which the model is told it is filling up. Defaults to 0.7. | | `context.compactThresholdRatio` | a number greater than 0 and less than 0.95 | | Share of the context window at which history is compacted. Defaults to 0.8. | | `history.maxConversationsPerAgent` | a whole number greater than 0 | | Conversations kept in each agent’s live history. Older conversations are archived, not deleted; active goal, loop and run conversations are protected. Defaults to 100. | | `workspaceMaxTotalBytesPerAgent` | a whole number greater than 0 | | Size cap for one agent's workspace directory, in bytes. Defaults to 1 GB. | | `scheduler.mode` | auto or in-process | | `auto` schedules workflows with launchd on macOS and cron on Linux; `in-process` leaves it to `jazz daemon`. See [Scheduling](./jazz.md#scheduling). | | `peers[].name` | text | | Local name for the peer, used in commands and the ledger. See [Agent-to-agent](../concepts/agent-to-agent.md). | | `peers[].url` | text | | The peer's endpoint, needed to ask them. | | `peers[].disclosure` | none, public, internal, or private | | The tier you grant this peer when it asks you. Unset grants nothing. | | `peers[].persona` | text | | Persona your agent answers this peer with. | | `peers[].allow` | a list | | Tools this peer may reach by name, beyond its disclosure tier. | | `peers[].budget.maxTokens` | a whole number greater than 0 | | Token ceiling for each run this peer starts. | | `peers[].budget.maxCostUSD` | a number greater than 0 | | Spend ceiling in US dollars for each run this peer starts. | | `peers[].budget.maxDurationMs` | a whole number greater than 0 | | Wall-clock ceiling in milliseconds for each run this peer starts. | | `peers[].maxConcurrentRuns` | a whole number greater than 0 | | Runs this peer may have in flight at once; a request past it is refused with `429`. Defaults to 4. | | `hosts[].name` | text | | Name of a machine registered for detached conversations. See [Detached conversations](../concepts/detach.md). | | `hosts[].sshTarget` | text | | SSH config alias for the machine. | | `hosts[].workspacePath` | text | | Absolute directory on the machine dedicated to Jazz transfers. | | `hosts[].allowFileSecrets` | true or false | | Let a machine without a keyring keep handed-off provider keys in its secrets file. Off by default. | | `webhooks[].name` | text | | Name in the webhook URL. See [Webhooks](../concepts/webhooks.md). | | `webhooks[].agentId` | text | | Agent the webhook runs. | | `webhooks[].promptTemplate` | text | | Prompt run when the webhook fires. `{{payload}}` becomes the request body, quoted as data. | | `webhooks[].description` | text | | What the webhook is for. | | `webhooks[].conversation` | ephemeral or threaded | | `ephemeral` starts fresh on each call; `threaded` continues one conversation. | | `webhooks[].disclosure` | none, public, internal, or private | | What the webhook's answers may reveal. Defaults to `internal`. | | `webhooks[].allow` | a list | | Tools the webhook run may reach by name, beyond its disclosure tier. | | `webhooks[].signature.format` | hmac-sha256 | | Authenticate each request by an `hmac-sha256` signature over its body instead of a bearer token. Set the shared secret with `jazz webhook secret `. | | `webhooks[].signature.header` | text | | Request header holding the signature. Defaults to `x-hub-signature-256`. | | `webhooks[].signature.prefix` | text | | Text before the hex digest in that header. Defaults to `sha256=`. | | `webhooks[].deliveryIdHeader` | text | | Header carrying each delivery's id; a delivery already received is refused. Defaults to `x-github-delivery`. | | `webhooks[].budget.maxTokens` | a whole number greater than 0 | | Token ceiling for each run this webhook starts. | | `webhooks[].budget.maxCostUSD` | a number greater than 0 | | Spend ceiling in US dollars for each run this webhook starts. | | `webhooks[].budget.maxDurationMs` | a whole number greater than 0 | | Wall-clock ceiling in milliseconds for each run this webhook starts. | | `webhooks[].maxConcurrentRuns` | a whole number greater than 0 | | Runs this webhook may have in flight at once; a request past it is refused with `429`. Defaults to 4. | | `daemon.token` | text | yes | The daemon's bearer token, written here only on a host without a keyring. Written by Jazz. | | `daemon.dailyCostUSD` | a number greater than 0 | | Most dollars unattended runs may spend per day, across all of them. Reaching it, or an unpriced unattended run today, pauses the daemon's own work until midnight or `jazz daemon resume`. Unset is unlimited. See [Spend caps](./jazz.md#spend-caps-and-notifications). | | `daemon.monthlyCostUSD` | a number greater than 0 | | Most dollars unattended runs may spend per local month, across all of them. Unset is unlimited. | | `daemon.dailyTokens` | a whole number greater than 0 | | Most prompt and completion tokens unattended runs may spend per day, across all of them. | | `daemon.goals.dailyCostUSD` | a number greater than 0 | | Combined goal-cycle and loop-run spend cap per local day, in dollars. Unset is unlimited. | | `daemon.goals.monthlyCostUSD` | a number greater than 0 | | Combined goal-cycle and loop-run spend cap per local month, in dollars. Unset is unlimited. | | `daemon.agents..dailyCostUSD` | a number greater than 0 | | Unattended spend cap per local day, in dollars, for the agent this key names (agent name or id). Unset is unlimited. | | `daemon.agents..monthlyCostUSD` | a number greater than 0 | | Unattended spend cap per local month, in dollars, for the agent this key names (agent name or id). Unset is unlimited. | | `notify.targets[].name` | a lowercase name of letters, digits, - and _ | | This target's name: the key its secrets are stored under (`notify.targets..`) and what a workflow's `deliver` field names. See [Notifications](./notifications.md). | | `notify.targets[].events` | a list | | Event subscriptions. Unset receives every subscribable event; workflow results go to the targets named by the workflow’s `deliver` field. | | `notify.targets[].kind` | desktop, ntfy, webhook, telegram, or discord | | Delivery transport: desktop, ntfy, webhook, telegram or discord. | | `notify.targets[].url` | an http:// or https:// URL | | ntfy topic URL, or the endpoint that receives each notification as a JSON POST (signed when the target has a secret). | | `notify.targets[].chatId` | text | | Telegram chat id to receive notifications. | | `notify.targets[].apiBaseUrl` | an http:// or https:// URL | | Override the Telegram or Discord API base URL for bot delivery. | | `notify.targets[].approveFromChat` | true or false | | Include chat approval commands in parked-run notifications. Requires a running bridge with operators and `JAZZ_APPROVALS_HOME` configured. Defaults to false. | | `notify.targets[].channelId` | text | | Discord channel id for delivery using a bot token. | | `ui.theme` | a theme name, optionally with :dark or :light | | The theme, such as `jazz`, `catppuccin:light` or a file in `~/.jazz/themes`. `/theme` writes it; `JAZZ_THEME` wins. Defaults to `system` (your terminal's own colours). | | `ui.canvas` | inherit or painted | | `inherit` leaves your terminal's background showing; `painted` fills every cell with the theme's background. Defaults to `inherit`. | | `chat.defaultCostLimitUSD` | a number greater than 0 | | Starting value of a new chat session's `/limit usd` cap, in dollars. `/limit` can still raise, lower or clear it for that session. Unset is unlimited. |