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.ai/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.ai/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
  }
}

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

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

Important runtime env knobs:

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

Deprecated Fields

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