Config

AlphaBase reads configuration from multiple sources and merges them into one runtime config object.

File Formats

AlphaBase accepts:

• JSON
• JSONC (JSON with comments and trailing commas)

Recommended header:

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
}

Value Interpolation

Config files support inline interpolation:

• {env:VAR_NAME}: substitute an environment variable
• {file:relative-or-absolute-path}: read file content and inject it

Example:

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}",
      },
    },
  },
}

Precedence (Low -> High)

Runtime merge order is:

1. Remote .well-known/alphabase config (if provider auth exposes one)
2. Global config (~/.config/alphabase/alphabase.json{,c})
3. Custom config path (ALPHABASE_CONFIG)
4. Project config (alphabase.json{,c} found upward in workspace)
5. .alphabase directory config + assets (agents/, commands/, plugins/, etc.)
6. Inline JSON (ALPHABASE_CONFIG_CONTENT)
7. Managed enterprise config directory (highest priority)

Merge Semantics

• Config is deep-merged, not replaced.
• plugin and instructions arrays are merged as unique unions.
• Legacy tools booleans are mapped into permission for backward compatibility.
• If autoshare: true is present and share is missing, AlphaBase migrates to share: "auto".

Top-Level Keys

| Key | Type | Purpose | | -------------------- | ---------------- | ------------------------------------------- | ---------------------- | ------------------------ | | $schema | string | JSON schema URL | | theme | string | UI theme | | keybinds | object | Keymap overrides | | logLevel | enum | Runtime log level | | tui | object | TUI behavior (scroll_speed, diff_style) | | server | object | serve / web listener config | | command | record | Inline slash command templates | | skills | object | Additional skill paths/URLs | | watcher | object | Ignore patterns for watchers | | plugin | string[] | Plugin module entries | | snapshot | boolean | Snapshot behavior toggle | | share | manual | auto | disabled | Session sharing behavior | | autoupdate | boolean | "notify" | Update policy | | disabled_providers | string[] | Provider blocklist | | enabled_providers | string[] | Provider allowlist | | model | provider/model | Primary model | | small_model | provider/model | Lightweight helper model | | default_agent | string | Default primary agent | | username | string | Chat display name override | | agent | record | Agent definitions/overrides | | provider | record | Provider/model override tree | | mcp | record | MCP server definitions | | formatter | object | false | Formatter config | | lsp | object | false | LSP server config | | instructions | string[] | Extra instruction files/patterns | | permission | object | string | Tool permission policy | | tools | record | Deprecated permission alias | | enterprise | object | Enterprise URL wiring | | compaction | object | Context compaction policy | | experimental | object | Feature flags and adaptive budget | | troubleshooter | object | Smart troubleshooter settings |

Server Config

{
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1",
    "mdns": false,
    "mdnsDomain": "alphabase.local",
    "cors": ["http://localhost:5173"],
    "tls": false,
  },
}

alphabase serve also accepts these as CLI flags directly (--port, --hostname, --mdns, --mdns-domain, --cors, --tls); explicit CLI flags take precedence over server config values. For any non-loopback hostname, set ALPHABASE_SERVER_PASSWORD — see Server.

Provider Config

provider.<id> supports:

• whitelist, blacklist
• models.<modelID> overrides
• models.<modelID>.variants.<name>.disabled
• options.apiKey
• options.baseURL
• options.enterpriseUrl
• options.setCacheKey
• options.timeout (number or false)

See Providers and Models.

Agent Config

You can override built-ins (alpha-v3, plan, general, explore) or define custom agents.

{
  "agent": {
    "alpha-v3": {
      "model": "<provider>/<model-id>",
      "permission": {
        "bash": "ask",
        "edit": "allow",
      },
      "steps": 12,
    },
    "reviewer": {
      "mode": "subagent",
      "description": "Read-only review agent",
      "permission": {
        "edit": "deny",
        "bash": "ask",
      },
    },
  },
}

MCP Config

Two MCP forms are supported:

• type: "local" with a command array (executable first, arguments after it), optional environment, enabled, and timeout
• type: "remote" with url, optional headers, optional oauth

Smart Router (Advanced)

AlphaBase’s opt-in model router/failover system is not a static alphabase.json key today — it is configured per request via the prompt’s agentOptions (modelRouter / modelRouting / smartRouting), and is off unless that request explicitly enables it. Full field reference: Models — Smart Router.

Routing is request-scoped today. There is no supported top-level config or environment switch that silently turns it on for every request.

Experimental + Adaptive Budget

Notable fields:

• experimental.batch_tool
• experimental.plan_auto_switch
• experimental.mcp_timeout
• experimental.adaptive_budget.enabled
• experimental.adaptive_budget.auto_model_fallback
• experimental.adaptive_budget.fallback_chain

Environment Overrides

Core config/runtime knobs:

• ALPHABASE_CONFIG
• ALPHABASE_CONFIG_CONTENT
• ALPHABASE_CONFIG_DIR
• ALPHABASE_DISABLE_PROJECT_CONFIG
• ALPHABASE_PERMISSION (merged into permission)

Model-specific stream deadline knobs:

• ALPHABASE_MINIMAX_IDLE_TIMEOUT_NO_TOOLS_MS
• ALPHABASE_MINIMAX_IDLE_TIMEOUT_WITH_TOOLS_MS
• ALPHABASE_MINIMAX_IDLE_TIMEOUT_SHALLOW_RETRY_MS
• ALPHABASE_MINIMAX_IDLE_TIMEOUT_POST_TOOL_MS

These apply to MiniMax cloud-Ollama stream handling and are bounded by the runtime. They do not enable a provider, change billing, or enable model routing. Task retry and recovery behavior is runtime-controlled; there are no public numeric environment caps documented here.

Deprecated Fields

• autoshare -> use share
• mode -> use agent
• tools -> use permission
• agent.maxSteps -> use agent.steps