Skip to content

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}",
},
},
},
}

Configuration Scope

Use Settings for ordinary app preferences. For file-based configuration, keep project settings in alphabase.json or alphabase.jsonc, and personal CLI defaults in ~/.config/alphabase/. An organization-managed installation can enforce policies. Check the effective settings if a project override does not apply.

Supported Keys

The published schema covers supported user settings. It is not an inventory of internal or experimental controls.

KeyPurpose
theme, keybinds, tuiAppearance and terminal preferences
serverLocal server listener settings
command, skills, plugin, instructionsUser commands and extensions
shareSession sharing preference
autoupdateUpdate preference
enabled_providers, disabled_providersAvailable provider restrictions
model, small_model, default_agentDefault model and agent choices
agent, providerUser agent and provider configuration
mcpConnected MCP servers
formatter, lspFormatting and language support
permissionAllow, ask, or deny tool actions

Keep keys and passwords out of committed configuration. Use an environment reference for credentials.

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

Model Routing (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 — Model Routing.

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

Custom Configuration Locations

ALPHABASE_CONFIG selects a config file, and ALPHABASE_CONFIG_DIR selects a configuration directory for supported CLI installations. Use these only when you intentionally need a separate configuration location. Restart the relevant process after changing its environment.

Deprecated Fields

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