docs blog library
github

Environment variables

Every variable Jazz reads, grouped by what it controls. A command-line flag wins over its variable, and a setting in config.json wins over a variable unless the row says otherwise. Boolean switches marked 1 accept only 1; anything else leaves them off.

Where Jazz keeps things

Variable Effect
JAZZ_HOME Directory for config, agents, conversations, memory, logs and secrets. Defaults to ~/.jazz. --data-dir wins.
JAZZ_CONFIG_PATH Global config file to use instead of $JAZZ_HOME/config.json. ~ is expanded.
JAZZ_LOG_DIR Directory for log files. Defaults to $JAZZ_HOME/logs.
JAZZ_DISABLE_KEYRING Any value other than empty, 0 or false turns off the OS keyring and the secrets-file fallback, so Jazz stores no secrets and reads keys only from the environment. Useful for CI and for isolated test homes.
JAZZ_DANGEROUSLY_ALLOW_READING_SECRETS Any value other than empty, 0 or false lets agents load saved secrets and use typed ones without a person approving each use, under every approval mode. Set by --dangerously-allow-reading-secrets. For unattended runs only.
JAZZ_CHATGPT_CREDENTIAL Optional JSON ChatGPT OAuth bundle used only when Jazz has no stored ChatGPT credential. Jazz removes it from child-process environments after reading it.
JAZZ_CHATGPT_CREDENTIAL_OUTPUT Optional file path where Jazz writes a rotated ChatGPT OAuth bundle after refresh. The file is created with mode 0600; use it only to persist the refreshed credential in hosted CI.
JAZZ_CHATGPT_ACCESS_TOKEN Optional bare ChatGPT access token another process keeps fresh. Jazz uses it until it expires or is refused, never refreshes it, never touches the stored sign-in, and removes the variable from child-process environments. Cannot be combined with JAZZ_CHATGPT_CREDENTIAL.

Terminal and display

Variable Effect
JAZZ_OUTPUT_MODE rendered, hybrid, raw or quiet. Wins over output.mode; --output wins over it. Other values are ignored.
JAZZ_NO_TUI 1 turns off the terminal UI entirely and prints plain output. --no-tui sets it.
JAZZ_FULLSCREEN 0 or false keeps the interactive UI but draws it inline instead of on the alternate screen.
JAZZ_A11Y, INK_SCREEN_READER 1 turns off the fullscreen interface, for screen readers.
JAZZ_THEME A theme name, optionally with :dark or :light, such as catppuccin:light. Wins over ui.theme. /theme lists available themes.
JAZZ_UI_GLYPHS unicode or ascii symbols. Detected from the terminal when unset.
JAZZ_TABLE_STYLE unicode, minimal or ascii borders for Markdown tables. Follows JAZZ_UI_GLYPHS when unset.
JAZZ_TERMINAL Overrides terminal detection, such as iterm2, terminal-app, warp or xterm. Detected from TERM_PROGRAM and TERM when unset.
JAZZ_NOTIFICATIONS_TERMINAL auto, osc99, osc777, osc9 or off: how desktop notifications reach the terminal. Wins over notifications.terminal. Other values are ignored. See Desktop notifications.
JAZZ_OSC7501 0, false or off turns off OSC 7501 program-status reports (the state=working / blocked / done signals terminals like Ghostty and Rex show in the tab). Emitted by default whenever a terminal is attached.
JAZZ_OSC_CWD 0, false or off turns off OSC 7 working-directory reports (tab titles, tmux). Emitted by default at the start of a session and a jazz run.
NO_COLOR, NODE_DISABLE_COLORS Any value turns color off.
VISUAL, EDITOR Editor for jazz persona edit and jazz mcp add, after the editor setting. Falls back to vi.

Network and catalogs

Variable Effect
JAZZ_OFFLINE 1 or true stops the requests Jazz makes on its own: the update check and the models.dev and library catalogs, which fall back to their caches. Model requests are unaffected. See Privacy.
JAZZ_DISABLE_UPDATE_CHECK 1 skips the update check when a command starts.
JAZZ_MODELS_DEV_URL Replacement URL for the models.dev catalog.
JAZZ_LIBRARY_URL Replacement base URL for the persona, workflow and skill library. Defaults to https://lvndry.github.io/jazz/library.
JAZZ_PLUGIN_CATALOG_URL Replacement base URL for plugin catalog ids. Defaults to https://lvndry.github.io/jazz/library/plugins/.
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY Route every request Jazz makes through a proxy. Lowercase forms win over uppercase; ALL_PROXY covers both schemes.

Runs, scheduling and the daemon

Variable Effect
JAZZ_GOLDEN_RECORD Path of a golden session fixture to write. When set, each streamed model call is scrubbed and recorded there. Maintainers only; see golden sessions.
JAZZ_GOLDEN_SCENARIO Scenario name stored in the recorded fixture. Defaults to the fixture file name.
JAZZ_STREAM_IDLE_TIMEOUT_MS How long a model stream may stay silent before Jazz abandons it, in milliseconds. llm.streamIdleTimeoutMs wins. Defaults to 120000.
JAZZ_SCHEDULER in-process leaves scheduled work to jazz daemon instead of launchd or cron, like scheduler.mode.
JAZZ_DAEMON_TICK_MS How often the daemon checks for due work, in milliseconds. Defaults to 5000.
JAZZ_DISABLE_CATCH_UP 1 skips the prompt to run workflows missed while the machine was off, and the failed-runs notice.

JAZZ_NOTIFY_<NAME>_<FIELD> supplies a notify target secret, taking precedence over the keyring: for example, JAZZ_NOTIFY_PHONE_BOT_TOKEN, JAZZ_NOTIFY_TEAM_WEBHOOK_URL, or JAZZ_NOTIFY_OPS_SECRET. Target names and field names become uppercase with underscores. See Notifications.

JAZZ_SPEND_LEDGER=parent tells a child process that its caller records its spend. The child skips its own ledger recording and cap checks; chat bridges set this to avoid counting a run twice. Leave it unset for standalone runs.

Model provider keys and servers

A provider key in the environment overrides a stored global key. An agent-specific config.llm.apiKeys override takes precedence over both. See Model providers for the order Jazz checks.

Provider Key variable
ai_gateway AI_GATEWAY_API_KEY
alibaba ALIBABA_API_KEY
anthropic ANTHROPIC_API_KEY (and ANTHROPIC_WORKSPACE_ID)
cerebras CEREBRAS_API_KEY
deepseek DEEPSEEK_API_KEY
fireworks FIREWORKS_API_KEY
gemini GOOGLE_GENERATIVE_AI_API_KEY, or GEMINI_API_KEY
groq GROQ_API_KEY
llamacpp LLAMACPP_API_KEY
minimax MINIMAX_API_KEY
mistral MISTRAL_API_KEY
moonshotai MOONSHOT_API_KEY
nvidia NVIDIA_API_KEY, or NIM_API_KEY
ollama OLLAMA_API_KEY (Ollama Cloud models)
openai OPENAI_API_KEY
openrouter OPENROUTER_API_KEY
orcarouter ORCAROUTER_API_KEY
refuseless REFUSELESS_API_KEY
sglang SGLANG_API_KEY
togetherai TOGETHER_AI_API_KEY
vllm VLLM_API_KEY
xai XAI_API_KEY
zhipuai ZHIPU_API_KEY

chatgpt has no key variable: sign in from /settings → Model providers in the jazz home screen. claude_code has none either: it uses your own signed-in claude; enable it with jazz config set claude_code.

Self-hosted servers are found at these addresses. A saved llm.<provider>.base_url wins over the variable.

Variable Default
OLLAMA_BASE_URL http://127.0.0.1:11434/api
LLAMACPP_BASE_URL http://127.0.0.1:8080/v1
VLLM_BASE_URL http://127.0.0.1:8000/v1
SGLANG_BASE_URL http://127.0.0.1:30000/v1

Web search keys: BRAVE_API_KEY, EXA_API_KEY, KEENABLE_API_KEY, LINKUP_API_KEY, PARALLEL_API_KEY, PERPLEXITY_API_KEY, TAVILY_API_KEY, and TREG_TOKEN. See Web search.

Daemon, peer and webhook tokens

Each is checked before the keyring.

Variable Effect
JAZZ_DAEMON_TOKEN The daemon’s bearer token.
JAZZ_PEER_TOKEN_<NAME> The token for one peer. <NAME> is the peer name in upper case, with every character outside A-Z and 0-9 turned into _.
JAZZ_PEER_TOKEN Where jazz peers set-token <name> reads the token from, unless --from-env names another variable.
JAZZ_WEBHOOK_TOKEN_<NAME> The token for one webhook, named the same way.
JAZZ_WEBHOOK_SECRET_<NAME> The signing secret for one webhook that uses signature, named the same way.
JAZZ_COMPANION_API_KEY_<NAME> The API key for one named companion, named the same way.

Telemetry

The standard OpenTelemetry variables configure OTLP export when telemetry.otlp does not: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS (and the per-signal _HEADERS forms), OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES. See Observability.

Tools and plugins

Variable Effect
PUPPETEER_EXECUTABLE_PATH Chrome or Chromium binary for the web page and PDF tools.
JAZZ_COMPUTER_DRIVER Path to the cua-driver executable for computer use. Searched on PATH when unset.
JAZZ_TERMINAL_NOTIFIER, TERMINAL_NOTIFIER Path to terminal-notifier for desktop notifications on macOS. The bundled copy is used otherwise.
JAZZ_LSP_CONFIG Server list for the lsp plugin. Defaults to ~/.jazz/lsp.json, whatever JAZZ_HOME is.
JAZZ_CLOUDFLARE_CONFIG Cloudflare credentials for publish_composition ({ "token", "accountId", "accessEmail", "pagesHost" }). Defaults to ~/.config/jazz/cloudflare.json.

Installer

install.sh reads these variables:

Variable Effect
JAZZ_INSTALL_DIR Directory for the binary. Defaults to ~/.local/bin.
JAZZ_VERSION Release to install, such as v0.15.44. Defaults to the latest.

Chat bots

The bridges read these when they start each run. Each bridge’s README has the full setup: Telegram, Discord, iMessage on your Mac, iMessage through Photon and WhatsApp.

Bridge controls:

Variable Effect
JAZZ_BOT_MAX_CONCURRENT_RUNS Maximum active runs across a bridge process. Positive integer; defaults to 4.
JAZZ_BOT_MAX_QUEUED_MESSAGES Maximum messages waiting behind a conversation’s active run: commands and other people’s messages. The requester’s own messages go into the run instead. Positive integer; defaults to 5.
JAZZ_BRIDGE_HEALTH_PORT Optional health HTTP port for iMessage, Photon and WhatsApp. Disabled when unset. Telegram and Discord use their existing HTTP servers.
JAZZ_APPROVALS_HOME Jazz home whose parked runs Telegram or Discord operators may approve or reject. Unset disables these chat commands. Runs as the bridge process, outside the conversation sandbox.

Shared by every bridge:

Variable Effect
JAZZ_APPROVAL_POLICY Approval policy for each run: read-only, low-risk or high-risk. Defaults to low-risk.
JAZZ_AUTO_APPROVE_TOOLS Comma-separated tools approved without asking.
JAZZ_REASONING Reasoning effort of the agent the bridge creates. Defaults to medium.
JAZZ_RUN_TIMEOUT_MS Time limit per run, in milliseconds. Defaults to 300000.
JAZZ_DAILY_COST_CAP_USD Daily spend cap in US dollars. 0, the default, means no cap.
JAZZ_BIN The jazz binary the bridge runs.
JAZZ_BUILTIN_PERSONAS_DIR Directory of built-in personas, set by the Docker images.
JAZZ_OLLAMA_KEEP_ALIVE Written to llm.ollama.keep_alive in the bridge’s config.
BRAVE_API_KEY Also selects Brave as the bridge’s web search provider.
JAZZ_BOT_DEFAULT_TIMEZONE IANA timezone (such as Europe/Paris) for a chat that has not set one with /tz. Unset, the agent asks the user for their zone; the server’s own TZ is never used.
JAZZ_BOT_CHAT_ISOLATION Gives each conversation its own user and home when the bridge runs as root with setpriv and useradd, as the Telegram and Discord images do. 0, false, off or no turns it off.
JAZZ_BOT_OPERATOR_GID Group allowed to read every conversation’s state. Defaults to the group owning the data directory.
JAZZ_BOT_RUN_AS Container user: in the Docker Compose files. Defaults to 0:0.
JAZZ_DEPLOY_BRANCH Branch auto-update.sh follows. See Keeping it updated.

Each bridge creates and runs its own agent. The agent id, provider and model apply when the bridge creates it; the provider defaults to openai.

Bridge Agent id (default) Provider and model Show reasoning (default)
Telegram JAZZ_TELEGRAM_AGENT (telegram) JAZZ_TELEGRAM_PROVIDER, JAZZ_TELEGRAM_MODEL JAZZ_TELEGRAM_SHOW_REASONING (on)
Discord JAZZ_DISCORD_AGENT (discord) JAZZ_DISCORD_PROVIDER, JAZZ_DISCORD_MODEL JAZZ_DISCORD_SHOW_REASONING (on)
iMessage on your Mac JAZZ_IMESSAGE_AGENT (imessage) JAZZ_IMESSAGE_PROVIDER, JAZZ_IMESSAGE_MODEL JAZZ_IMESSAGE_SHOW_REASONING (off)
iMessage through Photon JAZZ_PHOTON_AGENT (photon) JAZZ_PHOTON_PROVIDER, JAZZ_PHOTON_MODEL JAZZ_PHOTON_SHOW_REASONING (on)
WhatsApp JAZZ_WHATSAPP_AGENT (whatsapp) JAZZ_WHATSAPP_PROVIDER, JAZZ_WHATSAPP_MODEL JAZZ_WHATSAPP_SHOW_REASONING (off)

JAZZ_TELEGRAM_DYNAMIC_CTA and JAZZ_DISCORD_DYNAMIC_CTA offer follow-up buttons under replies; they are on by default.

Platform credentials, allowlists and addresses:

  • Telegram: TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_CHAT_IDS, TELEGRAM_MODE, TELEGRAM_WEBHOOK_URL, TELEGRAM_WEBHOOK_SECRET, TELEGRAM_WEBAPP_BASE_URL, NOMINATIM_BASE_URL, PORT.
  • Discord: DISCORD_BOT_TOKEN, DISCORD_ALLOWED_USER_IDS, DISCORD_ALLOWED_CHANNEL_IDS, DISCORD_ALLOWED_GUILD_IDS, DISCORD_REQUIRE_MENTION, DISCORD_CREATE_THREADS, DISCORD_PUBLIC_BASE_URL, PORT.
  • iMessage on your Mac: IMESSAGE_ALLOWED_HANDLES, IMESSAGE_ALLOWED_GROUP_CHAT_IDS, IMESSAGE_SELF_TRIGGER, IMSG_BIN.
  • iMessage through Photon: PHOTON_PROJECT_ID, PHOTON_PROJECT_SECRET, PHOTON_ALLOWED_HANDLES.
  • WhatsApp: WHATSAPP_ALLOWED_NUMBERS, WHATSAPP_ALLOWED_GROUPS, WHATSAPP_REQUIRE_MENTION_IN_GROUPS, WHATSAPP_AUTH_DIR, WHATSAPP_PAIR_NUMBER.

Test fixtures

These variables are private controls for the compiled terminal test fixture. The normal Jazz executable does not read them.

Variable Effect
JAZZ_PTY_CONTROL Validated control-file path used by the compiled PTY qualification fixture.
JAZZ_PTY_RESULT Result-file path used by that fixture to report native frame captures.

Set by Jazz

Jazz sets these for the processes it starts. Setting them yourself changes nothing useful.

  • JAZZ_AGENT_PROCESS marks a process an agent’s tool started, so jazz goal refuses decisions only you may make.
  • JAZZ_SURFACE names the surface that started a run (cli unless a bridge started it).
  • GIT_TERMINAL_PROMPT=0, and GIT_PAGER=cat unless you set your own, keep git from waiting on a password prompt or a pager inside a tool call.

machine-readable: /jazz/docs/configure/environment-variables.md · /llms.txt · /llms-full.txt