docs blog library
github

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 of minimal, low, medium, high, xhigh, or max 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, claude_code.
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.claude_code.enabled true or false Turns on the claude_code provider. Written by jazz config set claude_code after it finds a signed-in claude.
llm.claude_code.cli_path text Path to the claude binary when it is not on PATH.
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.
llm.openrouter.zdr true or false Send OpenRouter requests only to endpoints that retain no prompts or responses. See Model providers.
llm.openrouter.sort price, throughput, or latency Send OpenRouter requests to the cheapest (price), fastest (throughput) or quickest-to-answer (latency) endpoint first instead of load balancing across them. See Model providers.
web_search.<provider>.api_key text yes API key for the web search provider.
web_search.providers a list of exa, parallel, tavily, brave, perplexity, linkup, treg, or keenable Web search providers in fallback order, used when an agent does not name its own. Unset: every provider with a key. Empty: the model’s built-in search.
web_search.preferBuiltin true or false Use the model’s built-in search when its provider has one, and web_search.providers otherwise. Applies to agents without their own webSearchProviders. Defaults to false.
network.allowPrivateHosts a list of a hostname, *.suffix wildcard, IP address or CIDR block 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 of an exact HTTP(S) URL or trailing /* path prefix 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 of text 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 of traces, logs, or metrics 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.
history.toolResultRetentionDays a whole number of 0 or more Days an offloaded tool result is kept after its last write before a background sweep deletes it. 0 keeps them forever. Defaults to 30.
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 of text 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 of text 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 of waiting, paused, reminder, unattended-failed, or spend-cap 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.
shell.confinement off or on on fences model-run shell commands and the write_file, edit_file, create_pdf, rm, mv, cp and mkdir tools to writing under the working directory (and its repository), temp directories and well-known tool caches (reads and network stay open); off runs them unconfined. Unset is off in interactive chat and on for bots, peers, goals, loops and unattended jazz run. A project config can turn it on but not off. See Write confinement.
companions.<name>.provider openai, chatgpt, claude_code, anthropic, gemini, openrouter, xai, ai_gateway, alibaba, cerebras, deepseek, fireworks, groq, llamacpp, minimax, mistral, moonshotai, nvidia, ollama, orcarouter, refuseless, sglang, togetherai, vllm, or zhipuai Protocol the named companion speaks, e.g. vllm for any vLLM server. Agents bind it by name: "analyze:image": "<name>". Global config only; a project config’s companions is ignored. See Model companions.
companions.<name>.model text Model id the server serves, as its /v1/models lists it.
companions.<name>.base_url an http(s) URL without credentials Server for this companion only. Unset uses llm.<provider>.base_url.
companions.<name>.api_key text yes Key for this companion only, kept in the keyring (JAZZ_COMPANION_API_KEY_<NAME> on hosts without one). Unset uses the provider’s key.
companions.<name>.accepts a list of image, pdf, audio, or video Media the model reads (image, pdf, audio, video), overriding the model catalog. A role whose media is not listed is refused.
companions.<name>.prompt text Exact text sent with the media for analysis instead of Jazz’s task brief, for models trained on one instruction such as OCR:.

machine-readable: /jazz/docs/configure/config-reference.md · /llms.txt · /llms-full.txt