Configuration

SOBA reads configuration from several places with a clear priority: CLI flags > environment variables > config.json > defaults. This guide explains the main options and how they work together.

1. Configuration file

The configuration file is ~/.soba/config.json. SOBA creates it on first run, or you can write it by hand.

{
  "baseUrl": "https://api.deepseek.com",
  "apiKey": "YOUR_API_KEY",
  "model": "deepseek/deepseek-v4-flash",
  "maxOutputTokens": 8192,
  "maxCompletionTokens": 0,
  "reasoning": { "mode": "provider_default" },
  "contextWindow": 65536,
  "temperature": 0.7,
  "maxAgentIterations": 0,
  "maxStalledIterations": 4,
  "maxRunMinutes": 0,
  "bashMaxTimeoutSeconds": 300,
  "sessionDir": "~/.soba/sessions",
  "lang": "en",
  "theme": "graphite",
  "compaction": {
    "auto": true,
    "compactOnTurnComplete": true,
    "compactOnMilestone": true,
    "minTokensForAutoCompact": 32000,
    "minReclaimableTokens": 12000,
    "minSavingsRatio": 0.25,
    "keepRecentTokens": 20000,
    "safetyReserveTokens": 8192,
    "autoCompactThresholdRatio": 0.8,
    "timeoutMs": 15000
  },
  "registry": {
    "activeProvider": "deepseek",
    "activeModelId": "deepseek-v4-flash",
    "customProviders": []
  }
}

Minimal configuration:

{
  "apiKey": "YOUR_API_KEY",
  "model": "deepseek/deepseek-v4-flash"
}

2. Options

2.1. Provider

2.2. Model response

2.3. Runtime safety

2.4. Sessions

2.5. Interface

3. Environment variables

Environment variables override config.json.

4. CLI flags

CLI flags have the highest priority.

4.1. Run modes

4.2. Provider and model

4.3. Limits

4.4. Control and debugging

4.5. Info

5. Provider configuration

SOBA v0.6.x uses a provider registry. See Providers and models for details.

Built-in providers:

Models are discovered dynamically through GET /models and cached in the current process. Opening the model picker in the TUI with F2 or /model refreshes built-in providers.

Discovery also resolves model limits and reasoning controls when the provider publishes them. Explicit user limits take priority, followed by runtime/route/model metadata, maintained exact-model profiles, and finally conservative assumed values. SOBA does not infer capabilities from a model name. An assumed context window is shown with ~ in the model picker and produces a warning when selected.

Add a custom provider:

soba provider add my-llm \
  --base-url https://api.myllm.com/v1 \
  --api-key-env MY_LLM_KEY \
  --model my-code-model="My Code Model",128000,8192

Custom providers are saved in registry.customProviders.

Model-specific wire compatibility is declared in a complete provider JSON loaded with soba provider add <id> --from-file <path>. For example, "compatibility": ["single_system_message"] makes SOBA emit one leading system message for chat templates that reject multiple system messages. See model compatibility metadata for the full schema and supported features.

6. Compaction configuration

Compaction is configured through the compaction section.

Hard limit:

hardLimit = contextWindow - maxOutputTokens - safetyReserveTokens

When effective tokens exceed hardLimit, SOBA runs blocking compaction. This cannot be disabled with auto: false. See Compaction and Context Capsules for the complete lifecycle and threshold guide.

7. Precedence

CLI flags
    ↓ override
Environment variables
    ↓ override
config.json
    ↓ override
Defaults

Example: if config.json contains "theme": "graphite", SOBA_THEME=forest is set, and --theme paper is passed, SOBA uses paper.

Special rules:

• Reasoning precedence is request/session override → CLI → environment → config → provider default. /reasoning and F4 affect the next model request without restarting SOBA.
• Requested and effective reasoning are separate. Unsupported controls fall back to provider default with a visible reason; SOBA never silently clamps to a nearby level.
• maxOutputTokens and contextWindow are taken from the active model definition when possible. CLI flags and explicitly configured model limits override provider metadata for local proxies or incorrect catalogues.
• compaction.auto can be overridden by SOBA_AUTO_COMPACT=false or --no-auto-compact.
• Disabling auto-compaction turns off only soft triggers. Hard-limit and provider-overflow recovery remain mandatory.
• Turn and milestone triggers are deferred: SOBA shows progress and awaits compaction immediately before the next model call.
• Numeric 0 means unlimited for maxAgentIterations and maxRunMinutes; for maxCompletionTokens, it means no explicit limit.

8. Validation

SOBA validates configuration at startup:

• API key is required unless the selected provider is keyless.
• model is required.
• Compaction invariants must hold:
  • contextWindow > 0
  • maxOutputTokens > 0
  • safetyReserveTokens >= 0
  • maxOutputTokens + safetyReserveTokens < contextWindow
  • keepRecentTokens < contextWindow - maxOutputTokens - safetyReserveTokens

If compaction invariants fail, compaction is disabled with a warning:

⚠️  Compaction disabled: config validation failed:
    keepRecentTokens (50000) must be < hard limit (47360)