Configuration¶

Openbase CLI reads configuration from environment variables (usually loaded from ~/.openbase/.env).

Most day-to-day settings do not require editing this file: the desktop app and console Settings page cover backend, model, reasoning, voice providers, and environment variables, and the iOS app covers phone-side settings such as backend host and call audio. This page is the underlying reference.

Core Variables¶

Conversation Profiles¶

Setup installs Openbase profiles for both Codex and Claude Code. Normal terminal sessions retain their own model, reasoning, permissions, hooks, and MCP settings. Openbase may add shared skills and, by default, registers the Super Agents MCP server in the default Codex and Claude Code configurations so plain terminal sessions can dispatch Super Agents (pass --no-shared-super-agents-mcp to setup or profiles install to opt out; an existing entry of your own is never replaced). Setup does not create or replace the user's AGENTS.md or CLAUDE.md instructions.

Codex's openbase.config.toml is also usable with codex -p openbase. Codex does not accept --profile on app-server, so Openbase loads the same TOML file through thread/start and thread/resume configuration overrides. The shared daemon receives no global model, provider, reasoning, or service-tier overrides, including for the internal Cloud Codex backend. Role-specific model and reasoning choices are applied to the relevant conversation.

Claude Code uses --settings for a session-only profile rather than a named --profile option. Openbase supplies its settings and MCP files through the Claude SDK. Authentication and conversation storage remain in the user's existing Claude home; Openbase does not redirect CLAUDE_CONFIG_DIR or duplicate login credentials.

The Codex profile also registers the session-ID hook for native codex -p openbase commands. App-server configuration overrides do not guarantee execution of native file hooks; Openbase's Super Agents client supplies thread identity through developer instructions and shell environment independently. Claude runs its profile hooks through the native session settings layer.

Existing installations can run openbase-coder profiles install, then restart Openbase services. Setup and this repair command migrate identifiable Openbase MCP and session-ID hook entries out of user configuration, leaving unrelated entries intact. Pass --include-default-hooks to explicitly reinstall the session-ID hook in the default Codex and Claude Code configurations as well as the Openbase profiles. Changed user files receive a .before-openbase-profiles backup. Existing profile settings are preserved on repeated setup; invalid explicitly selected profiles fail instead of silently falling back to terminal defaults.

Dispatcher Config¶

Openbase runtime settings that are shared by LiveKit, CLI commands, and MCP tools live in ~/.openbase/dispatcher-config.json.

Useful keys:

Fresh Openbase Cloud installs write haiku for both roles, so the stored configuration, Settings UI, and model actually requested by the runtime agree. The catalog disables models that a free or trial account cannot run as named, including Sonnet, with the reason “Requires a paid plan.” The Cloud proxy continues to route older trial configurations that explicitly contain sonnet to Haiku for compatibility.

The voice model is picked like the agent model: one selectable id whose engine follows from it. openbase-coder defaults voice-model [MODEL] shows or sets this key (see defaults), as does the Voice Model setting in the desktop app, console, and the iOS and Android apps. A change applies to the next voice call; no restart is needed. LIVEKIT_VOICE_MODEL in the environment acts as a fallback when the key is absent.

Agent/Voice Variables¶

The voice worker on your computer or Cloud DevSpace accepts calls even when CPU load is high, for both GPT-Live and pipeline voice. This prevents load-based rejection from leaving your phone waiting for an agent; it does not guarantee audio quality on an overloaded machine. Deployments that intentionally share a worker can set LIVEKIT_AGENT_LOAD_THRESHOLD explicitly to limit load.

TTS Replacements¶

Openbase Coder formats spoken text before sending it to Cartesia. Built-in pronunciation defaults cover common acronyms such as AWS, API, TTS, and LLM.

To add or override pronunciations without rebuilding or restarting Openbase or the voice process, edit:

~/.openbase/tts-replacements.json

The formatter checks this file on each TTS formatting pass and reloads it when the path, modification time, or size changes. The file is optional. If it is missing or invalid, Openbase Coder keeps using built-in defaults.

Example:

{
  "acronyms": ["MCP"],
  "replacements": {
    "OpenAI": "Open A I",
    "foobarbaz": "foo bar baz"
  }
}

acronyms are spoken letter by letter and are matched case-insensitively. replacements and term_pronunciations are exact term-to-pronunciation maps.

Auth Modes¶

All protected API routes support either:

1. The owner-only installation capability in ~/.openbase/local-api-token, delivered out of band by the desktop app or openbase-coder auth open-console.
2. An owner JWT validated against OPENBASE_CODER_CLI_JWT_JWKS_URL (with fallback validation against OPENBASE_CODER_CLI_JWT_AUTH_SESSION_URL).

The capability file is created with mode 0600. Rotate it with openbase-coder auth print-local-api-token --rotate; clients holding the old value lose access immediately. There is no environment setting that disables this authentication boundary. WebSocket auth accepts the same credentials in its ?token= query parameter.