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
autoupdate	`boolean	”notify”`
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`
lsp	`object	false`
instructions	string[]	Extra instruction files/patterns
permission	`object	string`
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 (build, plan, general, explore) or define custom agents.

{
  "agent": {
    "build": {
      "model": "openai/gpt-5",
      "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 command, args, and optional env
• 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.

For a local/self-hosted instance, you can force routing/failover on for every request without per-call agentOptions using the environment overrides below (ALPHABASE_ALLOW_RUNTIME_MODEL_ROUTING, ALPHABASE_ALLOW_RETRY_MODEL_FAILOVER).

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 routing and task-recovery knobs (off/conservative by default; see Models and Task Execution):

• ALPHABASE_ALLOW_RUNTIME_MODEL_ROUTING (boolean, default false) — force-enable Smart Router for every request on this instance, without per-call agentOptions.
• ALPHABASE_ALLOW_RETRY_MODEL_FAILOVER (boolean, default false) — force-enable failover-on-stuck-attempt for every request on this instance.
• ALPHABASE_MAX_SYNTHETIC_DELIVERABLE_RECOVERIES (integer, default 3, range 1-10) — cap on synthetic recovery turns per task before AlphaBase stops with a clear failure message.
• ALPHABASE_MAX_LOOP_STEPS_CEILING (integer, default 40, range 8-200) — finite ceiling on total loop steps per task when no other budget applies.
• ALPHABASE_MINIMAX_IDLE_TIMEOUT_NO_TOOLS_MS / _WITH_TOOLS_MS / _SHALLOW_RETRY_MS / _POST_TOOL_MS — idle-timeout tuning for reasoning-heavy cloud Ollama models (these default to several minutes, far longer than the default for fast non-reasoning models, so a thinking model isn’t cut off mid-reasoning).

Deprecated Fields

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