Configuration reference#

ThinkWatch Core reads one file, config.yaml. This page describes every field in it: what it does, its default, the values it takes, and how a change reaches the running process. To run core on a server and control it from the desktop app, see Running core on a server.

The field tables on this page are generated from the code, and a test fails when they disagree, so a field listed here is a field the binary reads.

Where the file is#

THINKWATCH_HOME replaces the directory, and --config <path> names the file for a single command. The directory holds everything else core keeps as well: the request database (data.db), the configuration history (history/), the downloaded price table (model_prices.json) and the local control socket (twcore.sock; on Windows a loopback port recorded in control.port). The directory is private to its owner (0700), the file is 0600: it holds keys in plain text.

twcore serve writes a starting configuration when there is none, and twcore init writes one on request. Both produce this:

version: 1
listen:
  control:
    key: 6629…753d       # generated
clients:
  - name: default
    key: tw-…            # generated

That is a complete, valid configuration. It has no upstream yet, so the control plane runs and requests are answered with an error saying so. Adding one upstream makes it forward:

providers:
  - name: anthropic
    base_url: https://api.anthropic.com
    key: ${ANTHROPIC_API_KEY}

How the file is read#

• A field name that is not in this reference is an error. A misspelled prot: is not ignored while the gateway quietly starts on the default port; the whole file is refused and the message names the field.
• Defaults are not written into the file. Anything left out has the default in the tables below. The app and the command line add a field only when its value differs from the default, so what is in the file is what someone chose.
• ${VAR} reads an environment variable in fields marked “${VAR} allowed”: upstream keys, header values, proxy passwords. It is read from the environment of the core process when a request is sent; an unset variable fails that upstream’s requests and names the variable. Under systemd, that environment is the unit’s EnvironmentFile.
• Names are references. Rules, groups and keys refer to upstreams, groups, routes and price sheets by name. A name that points nowhere is an error at load time rather than a rule that never matches. Renaming in the app changes every reference in the same write. Names starting with __ are reserved for built-ins.
• version is the format version, 1. A file with a higher version was written by a newer twcore and is refused.

How a change takes effect#

There are three ways to change the configuration, and they all go through the same path: the desktop app, twcore config …, and editing the file in an editor. Core watches the file and reloads it within a second of a save; nothing needs to be restarted.

A new version is applied only if it passes every stage:

1. It parses as YAML.
2. It matches the schema: known fields, the right types.
3. It is consistent: names are unique, references resolve, patterns compile, CIDR ranges are well formed.
4. The runtime objects can be built from it.

If any stage fails, the previous configuration stays in service, and the error says which stage failed and where. A typo never takes the gateway down. The desktop app shows the rejection until a valid version is saved.

Changes to listen.gateway apply live as well: core opens the new listener, and if it cannot (the port is taken) it keeps the old one and reports why. Retention changes are applied on the next hourly clean-up.

When two writers edit at once (the app and a hand edit), the second write is refused with a version mismatch instead of overwriting the first.

History and rollback#

Every version that was in effect is kept in history/ beside the file, with where it came from (the app, the command line, an outside edit, a rollback, a credential rotation). The last 50 are kept.

twcore check                      # validate the file without starting anything
twcore config show                # print it, with its version
twcore config history             # list the versions, newest first
twcore config rollback 3f9a2c     # go back to a version (a prefix is enough)
twcore config set /listen/gateway/port 8790 --int

These commands work on the file directly, so they work when core is not running, which is when a rollback is most needed. A running core picks their changes up like any other save.

twcore config set <path> <value> changes one value that is already written in the file. The path names list items by their name (/providers/anthropic/base_url); a number is an index (/routes/0/rules/1/to). The value is a string unless --int, --bool or --null says otherwise. The result is validated before it is written. To add a field that is not in the file yet, edit the file.

Credentials the gateway writes back#

One write is not made by a person. When an upstream’s OAuth token endpoint issues a new refresh token, the old one stops working, so the gateway writes the new token (and the access token with its expiry) back into providers[].oauth. Only those values change; comments and layout are left as they are.

Reference#

Each table lists every field of one section. ”—” in the Default column means the field is simply absent unless written; the description says what that means.

Top level#

listen#

Where core accepts connections. There are two kinds: the AI gateway that clients send requests to, and the control channel the desktop app and twcore commands use.

listen.gateway#

When bind reaches beyond this machine, allow_from decides who gets in. The gateway has no TLS: expose it on networks you trust, or put it behind a tunnel or VPN.

listen:
  gateway:
    bind: all
    port: 8788
    allow_from: [192.168.1.0/24]

listen.control#

The control channel is how the desktop app, and twcore config and twcore control-key on the same machine, talk to core. Locally it is a socket file in the data directory (a loopback port on Windows); no network port is opened for it unless remote is enabled.

Every control connection, local or remote, starts with a handshake that proves both ends hold key (Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s: the key is the pre-shared key, each connection negotiates fresh session keys, and the traffic is encrypted). There are no certificates. A peer without the key cannot complete the first message.

key is written by twcore serve before the control channel starts listening, if it is missing, and by twcore init. It is masked wherever the configuration is shown or kept in the history; saving a masked value back keeps the real one. A missing or malformed key (not 64 hexadecimal characters) makes the whole file invalid, so it cannot be replaced by a short, guessable one.

twcore control-key            # print the key, to paste into the desktop app
twcore control-key --rotate   # replace it; connected apps have to reconnect

Both run on the machine where core runs.

listen.control.remote#

A network port for a desktop app on another machine. It is opened in addition to the local channel, so a mistake here (a port that is taken, an allow_from that shuts you out) never locks out the machine itself: twcore config and the local app keep working.

listen:
  control:
    key: 9f2c…e41a          # 64 hexadecimal characters
    remote:
      enabled: true
      bind: all
      port: 23483            # random, written when the section is generated
      allow_from: [192.168.1.0/24]

A connection over the remote port cannot do three things, whatever the app asks: shut core down (it is managed by systemd), change listen.control (the door it came in through), or produce a diagnostic bundle (it would be written on the server). Handshakes time out after 5 seconds; five failed handshakes from one source within a minute block that source for a minute.

clients#

Gateway keys: the keys clients such as Claude Code and Codex send to the gateway. A key is an identity. Limits, model scope and route are per key.

clients:
  - name: default
    key: tw-a3f9c8d1e5b2h7k4m6n8p2q4
  - name: build-server
    key: tw-q8r2s4t6u8v2w4x6y8z2a4b6
    max_concurrent: 4
    allow: [claude-sonnet-*]
    route: cheap

providers#

Upstreams: the APIs requests are forwarded to.

A credential is one of four things: key, which goes in the header the protocol expects; oauth, a token obtained from a refresh token; aws, the access keys a Bedrock upstream signs its requests with; or headers, when the upstream wants something of its own. headers can be combined with the others, except for the header that already carries the credential.

providers:
  - name: anthropic
    base_url: https://api.anthropic.com
    key: ${ANTHROPIC_API_KEY}

  - name: relay
    base_url: https://relay.example.com/v1
    protocol: openai-chat
    headers:
      X-Relay-Token: ${RELAY_TOKEN}
    proxy: office
    models_only: [gpt-4.1*, o3]
    pricing: relay-discount

  - name: local
    base_url: http://127.0.0.1:11434/v1
    protocol: openai-chat
    billing: free

A request carries the request itself and the headers its upstream needs, and nothing else from the client: the credential and the headers written in headers; ThinkWatch’s own User-Agent; and, from the client’s request, only the headers the upstream’s protocol uses (anthropic-* for Anthropic, Idempotency-Key and X-Client-Request-Id for OpenAI, none for Gemini). Identity fields that clients fill in themselves, such as Claude Code’s metadata.user_id, are removed from the body. For an upstream that admits only certain clients, turn on forward_client_identity.

A ChatGPT account upstream (protocol: chatgpt) takes only the credential the desktop app obtains by signing in; it cannot be written by hand. Claude and Google subscription sign-ins are not supported; use an API key.

providers[].oauth#

The access token goes in the protocol’s authorization header. To put it somewhere else, write the header in headers with {{access_token}} where the token goes:

    oauth:
      refresh: ${VENDOR_REFRESH_TOKEN}
      endpoint: https://auth.example.com/oauth/token
      client_id: my-client
    headers:
      X-Access: Token {{access_token}}

providers[].aws#

A Bedrock upstream authenticates in one of two ways. A Bedrock API key goes in key and is sent as Authorization: Bearer. AWS access keys go in aws, written there or read with aws.profile from a profile in the AWS credential files: every request is signed with them (SigV4) once its body is final, and the keys themselves are never sent. Keys written in the configuration can be read from the environment with ${VAR}. A profile is read from the files on the machine core runs on, and read again when they change, so a tool that refreshes temporary keys in ~/.aws/credentials needs no restart. Nothing runs a command to obtain a credential, so a profile that signs in through IAM Identity Center (aws sso login), runs a credential_process or assumes a role cannot be used; export the keys it produces instead.

providers:
  - name: bedrock
    base_url: https://bedrock-runtime.us-east-1.amazonaws.com
    key: ${AWS_BEARER_TOKEN_BEDROCK}

  - name: bedrock-keys
    base_url: https://bedrock-runtime.eu-west-1.amazonaws.com
    aws:
      access_key_id: ${AWS_ACCESS_KEY_ID}
      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
      session_token: ${AWS_SESSION_TOKEN}

  - name: bedrock-profile
    base_url: https://bedrock-runtime.us-west-2.amazonaws.com
    aws:
      profile: dev

Requests are converted to Converse. The model list comes from the region’s control plane: the foundation models that can be invoked on demand, the inference profiles AWS defines (us.anthropic.claude-…), and the account’s application inference profiles, listed by the ARN they are invoked by. Listing needs bedrock:ListFoundationModels and bedrock:ListInferenceProfiles; without them requests are still forwarded, and models can list the models by hand. For a VPC endpoint or a proxy, write its address in base_url and the region in aws.region; the model list is asked of that address too.

proxies#

Outbound proxies. Different upstreams often need different ones, so there is no global switch: an upstream picks one with proxy.

proxies[].auth#

proxies:
  - name: office
    type: http
    addr: proxy.example.com:3128
    auth:
      user: alice
      pass: ${PROXY_PASSWORD}

on_proxy_fail: fail is the default because falling back silently sends a request by a path you did not intend; you would believe you were on the proxy while you were not.

pricing#

The cost of a request is its usage times the price of the model. Prices come from the default price table (LiteLLM’s public dataset, a copy of which is built into the binary and refreshed daily) or from a price sheet an upstream picks. A change of price applies to requests from then on, never to ones already recorded.

pricing.sheets#

pricing.sheets[].models#

Prices are in US dollars per million tokens, as printed on vendors’ price pages. Every field is written out; nothing is inferred when pricing.

pricing:
  sheets:
    - name: relay-discount
      multiplier: 0.8
      models:
        claude-sonnet-4-5-thinking:
          input: 3
          output: 15
          cache_read: 0.3
          cache_write_5m: 3.75
          cache_write_1h: 6

client_probes#

Some requests clients send are not the user’s: connectivity checks, warm-ups, session titles, topic detection, suggestions. Each class can be answered locally (intercept, nothing is sent upstream), passed through (passthrough), or handed to the routing rules (route, matched with when.intent). The defaults intercept only what nobody would miss.

security#

Five guards, applied to every upstream alike. Each has a mode: off, observe (detect and record, change nothing) or enforce (act). They start in observe, except the output limit, which starts off. What enforce does differs per guard, and each says so below.

security.redact#

Before a request leaves, credentials in it are looked for. Under enforce they are replaced.

Built-in rules:

security.inspect_tools#

Tool calls a model returns are checked against the rules. Under enforce, a match with rules set to cut stops the response, so the client never receives a complete call to run.

Built-in rules:

security.hidden_text#

Characters people cannot see and models can read, in what the caller sends (tool results included). Under enforce, the request is refused.

security.content#

Words or patterns in what the caller sends. Under enforce, a match with rules set to block refuses the request.

Built-in rules:

security.output_limit#

security:
  redact:
    mode: enforce
    enable: [internal-ip]
    custom:
      - name: employee-id
        pattern: 'EMP-\d{6}'
  inspect_tools:
    mode: enforce
  output_limit:
    mode: enforce
    max_chars: 200000

retention#

Two limits, because the two kinds of data differ in size by three orders of magnitude: request bodies are tens of kilobytes each, a request’s record a few hundred bytes. The byte limit covers bursts.

failover#

An upstream that fails is set aside for a while, so that the next requests go straight to the next candidate. How long depends on the reason the upstream gives: an insufficient balance waits for a top-up, a used-up quota waits until the moment the upstream says it resets, and a rate limit usually passes within seconds. A request with a single candidate is never affected.

Before the first content of a streamed answer reaches the client, an error the upstream sends in the stream moves the request to the next candidate, the same as an error status would.

groups#

A group puts several upstreams behind one name. Rules send requests to a group with to.

fallback is the default because a single user’s machine has no load to spread.

Whatever the type, a conversation stays on the upstream that last answered it, so that what the upstream holds of it in its prompt cache is read again rather than paid for in full elsewhere. Within a turn (while the client sends tool results back) it always stays; across turns it stays while the previous answer read or wrote at least 1024 tokens of prompt cache and came less than five minutes ago. An upstream that is cooling down after failures releases the conversation, and whichever upstream answered after a failover is the one it stays on. The rule a turn matched at its start also holds for the rest of that turn: rules keyed on input size or images do not move a turn halfway, unless its input no longer fits the context window of a model the rule sends it to. load-balance therefore takes turns between new conversations.

routes#

A route is a list of rules evaluated top to bottom. Each key takes the route named in its route, otherwise default_route, otherwise the route named default; without any, requests fail over across all upstreams in the order they are declared.

routes[].rules#

routes[].rules[].when#

A comparison starts with >, >=, <, <= or ==, and the number may end in k or m: ">200k", "<=4k". Without an operator it is an error, not an equality: "200k" alone is refused.

routes[].rules[].set#

groups:
  - name: fast
    type: url-test
    providers: [anthropic, relay]

routes:
  - name: default
    rules:
      - name: long context goes to the official API
        when: { input_tokens: ">200k" }
        to: anthropic
      - name: titles go to the cheap model
        when: { intent: titling }
        set: { model: claude-haiku-4-5 }
      - name: everything else
        to: fast
default_route: default

Environment variables#