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. <provider>, <model>, <server> and <header> 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.

Jazz configuration explains how global and project files merge, and the agent file 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.<provider>.<model>.reasoning.kind`	unsupported, toggle, effort, manual, adaptive, or budget		Which reasoning control the model accepts. See Model providers.
`llm.capabilityOverrides.<provider>.<model>.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.<provider>.<model>.reasoning.canDisableReasoning`	true or false		Whether the model accepts reasoning turned off.
`llm.capabilityOverrides.<provider>.<model>.reasoning.efforts`	a list		Effort levels the model accepts, for `effort`, `adaptive` and `manual`.
`llm.capabilityOverrides.<provider>.<model>.reasoning.minimumBudgetTokens`	a whole number greater than 0		Smallest thinking budget the model accepts, for `manual` and `budget`.
`llm.capabilityOverrides.<provider>.<model>.reasoning.maximumBudgetTokens`	a whole number greater than 0		Largest thinking budget the model accepts, for `manual` and `budget`.
`llm.capabilityOverrides.<provider>.<model>.supportsTools`	true or false		Whether the model can call tools, overriding the model catalog.
`llm.<provider>.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. 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.<provider>.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.<provider>.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.
`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.
`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.<server>.enabled`	true or false		Turn a server defined in `.agents/mcp.json` on or off.
`mcpServers.<server>.trusted`	true or false		Let the server’s tool annotations set their risk level. See MCP.
`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.
`autoApprovedCommands`	a list		Shell commands approved without asking. See Approvals.
`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.<header>`	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.<attribute>`	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.
`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.
`peers[].name`	text		Local name for the peer, used in commands and the ledger. See Agent-to-agent.
`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.
`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.
`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 <name>`.
`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.
`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.<agent>.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.<agent>.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.<name>.<field>`) and what a workflow’s `deliver` field names. See Notifications.
`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.