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,
  "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,
    "backgroundTimeoutMs": 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.4.0 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 Ctrl+M refreshes built-in providers.

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.

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. The full compaction guide is currently available in Russian: Compaction and Context Capsules.

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:

• maxOutputTokens and contextWindow are taken from the active model definition when possible. CLI flags override them for advanced cases such as local proxies with incorrect model metadata.
• compaction.auto can be overridden by SOBA_AUTO_COMPACT=false or --no-auto-compact.
• 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)