Configuration

This is the reference for Joe’s configuration file and environment surface: every key, every environment variable, and the default each one resolves to. For a guided first run see the Quickstart; for the build-and-run procedure see Install and Build; for why Joe is configured the way it is see Concepts.

Joe needs no configuration file to run. It boots on built-in defaults; a config file becomes useful when you want to pin a model, run more than one model, enable OIDC login, or tune the server. The one thing Joe will not boot without is an identity configuration — at least one service account or a complete OIDC issuer (see Install and Build).

Config file location

Joe reads its config file from the first of these that is set:

1. the --config <path> flag,
2. the JOE_CONFIG environment variable,
3. ~/.joe/config.yaml (the default).

A missing config file is not an error. The file is YAML; provider API keys are never stored in it — they live only in the environment that runs the daemon.

Config file reference

The block below shows every key with its real default. Keys whose value is currently inert are marked and collected under Inert and reserved keys.

llm:
  current: claude-sonnet              # key into llm.available — the active model
  available:                          # default seeds exactly this one entry
    claude-sonnet:
      provider: claude                # one of: claude | gemini | openai-compat
      model: claude-sonnet-4-20250514
    gemini-flash:
      provider: gemini
      model: gemini-2.5-flash
    local-llama:
      provider: openai-compat         # generic OpenAI Chat Completions endpoint
      model: llama3                   # the model name the endpoint expects
      base_url: http://localhost:11434/v1  # REQUIRED for openai-compat; ignored otherwise
  currency: USD                       # USD | EUR (EUR conversion is inert — see below)
  usd_to_configured_rate: 0           # reserved; validated but unused (see below)

server:
  address: "localhost:7777"           # daemon listen address
  service_accounts:                   # machine identities; each key → principal svc:<name>
    - name: server                    # the "server" account is the key the joe CLI presents
      key: "a-long-random-secret"
    - name: ci
      key: "another-secret"
  tls_cert_file: ""                   # server TLS is enabled only when BOTH cert and key are set
  tls_key_file: ""
  tls_enabled: false                  # CLIENT-side flag: connect over HTTPS (not a server TLS switch)
  rate_limit_rps: 0                   # per-IP requests/sec (0 = rate limiting disabled)
  rate_limit_burst: 0                 # per-IP burst (no default; see below)
  session_archive_dir: ""             # "" → ~/.joe/session-archive

auth:                                 # human login (OIDC); optional
  admin_email: ""                     # bootstrap admin identity ("" = bootstrap disabled)
  session_ttl: 12h
  post_login_redirect: "/"
  oidc:                               # OIDC active only when issuer + client_id + redirect_url are all set
    issuer: ""
    client_id: ""
    client_secret: ""
    redirect_url: ""

refresh:                              # NOTE: this whole block is currently inert (see below)
  interval_minutes: 5
  llm_budget:
    max_calls_per_hour: 100
    batch_threshold: 10
    batch_timeout_sec: 30

logging:
  level: info                         # debug | info | warn | error
  file: ""                            # log file path ("" = stderr only)

database:
  driver: ""                          # "" → sqlite (the only functional driver today); "pgx" is present but not yet operational — see note below
  dsn: ""                             # "" → joe.db in Joe's .joe directory; an explicit value is an absolute path, and ~ is NOT expanded
  encryption_key_path: ""             # "" → encryption.key in Joe's .joe directory; same rules as dsn — move it with the database

skills:
  trusted_sources: []                 # repos auto-trusted for skill install ([] = allowlist off)
  hot_reload_disabled: false

web_search:                           # optional; web search is inert until a provider is set
  provider: ""                        # "" = disabled; the only supported value today is "searxng"
  base_url: ""                        # REQUIRED when provider is set (the search endpoint or a gateway)
  api_key: ""                         # optional; SearXNG normally needs none

Key reference

llm

server

auth

logging

database

The defaults above are resolved locations, not literals to copy. An explicit value of either must be an absolute path (or one relative to the working directory): Joe does not expand a leading ~ in either value, so ~/.joe/joe.db is taken literally and creates a directory named ~ in the working directory. The two behave identically by design.

Set them together. The database and the key are one unit of durable state, and relocating only the database strands the key under the home directory. Joe will not start if the key is missing or does not match the database it finds, so a half-relocated install fails at start-up rather than running broken — see Persistence and backup.

PostgreSQL is not yet functional. The pgx driver value exists in the configuration surface — the store opens the configured driver, the repositories are dialect-aware, and the migration runner has a PostgreSQL branch — but the embedded migration set is written in SQLite dialect only. Setting database.driver: "pgx" today fails at startup during the migration step, before the server begins serving, because those migrations use SQLite-only constructs (AUTOINCREMENT and SQLite-specific append-only trigger DDL) that PostgreSQL rejects. Use the default SQLite backend. PostgreSQL support is planned.

skills

web_search

Web search is a global, boot-resolved capability shared by every chat session. What it does and how it is classified as a Read on Joe’s action surface is explained in The action model; the keys are below.

When no provider is configured the web_search tool is still offered to Joe but every call returns a no search backend configured error — it is never silently hidden. A misconfigured backend (an unknown provider, or searxng without a base_url) fails the daemon at boot. Changing the backend requires a restart; there is no runtime switch.

SearXNG (recommended self-host backend). SearXNG is a self-hostable, keyless metasearch engine. Point base_url at your instance and enable JSON output on it — SearXNG serves JSON only when json is listed under search.formats in its settings.yml (the default configuration omits it). Joe queries the instance’s /search endpoint with format=json and reads each result’s title, URL, and snippet.

web_search:
  provider: searxng
  base_url: https://searxng.internal.example.com

Keyed hosted providers (e.g. Tavily, Brave) are a designed-for extension behind the same provider abstraction but are not implemented yet. When added, their keys will ride plain config/env like the LLM provider keys — not the component credential-reference model.

Environment variables

Config overrides

Boot and process

Provider API keys

Provider keys live only in the environment that runs the daemon; client subcommands never read them.

Client subcommands

The joe mcp and joe slack subcommands are clients of a running daemon and read their connection settings from the environment.

OpenTelemetry

Static credential references

A static (env-var) credential reference for a component is an environment variable named JOE_<SEGMENT>_<LABEL>, where <SEGMENT> is the component type’s fixed prefix segment and <LABEL> is your choice (e.g. PROD, STAGING). For example, a GitHub component references JOE_GITHUB_PROD. The segments are defined for the static credential types listed in Components. The credential value lives only in that environment variable; promotion stores the variable name, never the value.

Provider configuration

Joe is AI-agnostic. The accepted providers are exactly:

• claude — native Anthropic adapter.
• gemini — native Google adapter.
• openai-compat — generic adapter for any server speaking the OpenAI Chat Completions protocol, selected together with a per-model base_url.

Any other provider value is rejected at config validation. A model using openai-compat must set base_url; native providers ignore it.

Inert and reserved keys

These keys are parsed (and some are validated) but have no effect in the running binary today. They are documented here so they are not mistaken for operative knobs.

Where to go next

• A guided first run → Quickstart
• Build and run the daemon, and the full authentication posture → Install and Build
• Connect Joe to your systems → Components
• Why Joe is governed by construction → Concepts