Environment variables

Every variable on this page has a reader in the code. It was compiled by finding the call sites, not by reading the example files — an .env.example is documentation, and documentation drifts.

Variables come in three shapes, and the shape decides when a change takes effect.

Overrides of a stored setting. Seventeen names shadow the seventeen runtime settings. They are read at every use, so a change takes effect on the next request — unless someone has saved that setting in settings.yaml, in which case the saved value wins and the variable is ignored. See The settings reference.

Environment-only, read at use. No setting behind them, but read fresh each time, so a restart is enough.

Environment-only, read at import. Read once when the module loads. Changing them on a running server does nothing; the process has to be restarted.

An empty value is usually "unset" — twice it is not

Most readers treat KOTOBA_X= exactly like an absent KOTOBA_X: the ten import-time limits read a blank as "use the default" on purpose. A blank now short-circuits before the validator runs, so KOTOBA_SANDBOX= or KOTOBA_MODEL= falls back to the default silently; an unusable value like KOTOBA_SANDBOX=rocket is what fails validation and says so in the log.

One does not, and it means to. Measured, with the variable exported empty and nothing saved:

That one is deliberate and pinned by a test. Everywhere else a blank is now read as unset and falls back to the default, so blanking a line to comment it out no longer disables anything by accident — KOTOBA_EXPRESSIVE= used to take the [audio tags] with it and no longer does. To turn reasoning off on purpose, write off rather than leaving the value empty.

---

Keys

An in-app saved key beats the environment for the three that have both paths (the two providers and ElevenLabs). Saved keys live encrypted in the database and are decrypted into memory at startup.

A value that looks like a template counts as no key at all: anything containing ..., …, <, >, or that reduces to one of a short list of placeholder words once an sk-/xai-/el_ prefix is stripped. This is why OPENAI_API_KEY=sk-... copied unedited from the example file reads as unset rather than producing a 401 on every turn.

Where things live

Every one of these is environment-only and read at use, except where noted.

Network and access

The brain

Voice

Execution, browser and MCP

Work-mode limits

Live settings, changeable from the panel: work_timeout, work_max_iter, work_max_tool_calls, work_fail_limit — variables KOTOBA_WORK_TIMEOUT, KOTOBA_WORK_MAX_ITER, KOTOBA_WORK_MAX_TOOL_CALLS, KOTOBA_WORK_FAIL_LIMIT.

Two of those four also have an import-time twin in the loop's module constants. Ignore it: those constants are only a fallback for a runtime read that fails to parse, and the validator makes that unreachable. The runtime path is what decides.

The rest are read at import and cannot be changed on a running server:

A blank value here is not an error and not a zero: it is read as "unset" and the default applies. That matters because the shipped api/.env.example leaves six of these uncommented.

Rate limiting

Read at use, no setting: KOTOBA_TPM_FLOOR (35000 tokens — wait for the window to reset below this), KOTOBA_TPM_MAX_PACE (75 seconds — the longest wait taken on Kotoba's own header arithmetic), KOTOBA_MAX_RETRY_AFTER (120 seconds — the longest server-supplied Retry-After actually slept).

Odds and ends

The terminal reads a handful of its own presentation variables — NO_COLOR, KOTOBA_REDUCED_MOTION, KOTOBA_NO_GRAPHICS, KOTOBA_FORCE_PORTRAIT, KOTOBA_FORCE_BACKGROUND, KOTOBA_MEASURE, KOTOBA_CLI_FACES, KOTOBA_PRESS_MS, KOTOBA_HOLD_S, KOTOBA_CLIPBOARD, KOTOBA_CLIPBOARD_PNG — which change nothing but how the screen is drawn.

Variables the browser bundle reads

These are compiled into the JavaScript by next build. Setting them on a running server does nothing; see Running it for real.

The two NEXT_PUBLIC_* first-paint values are only a first paint. Once the app has a token it asks /api/settings and the saved voice_mode and elevenlabs_agent_id replace them.

Only three variables are read by the Next server at run time: KOTOBA_WEB_PASSWORD, KOTOBA_GATE_PASSWORD and KOTOBA_GATE_SECRET. If you run the frontend as its own process, those are the three it needs in its own environment — and they must match the backend's.