Config
AlphaBase reads configuration from multiple sources and merges them into one runtime config object.
File Formats
AlphaBase accepts:
JSONJSONC(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.
| Key | Purpose |
|---|---|
theme, keybinds, tui | Appearance and terminal preferences |
server | Local server listener settings |
command, skills, plugin, instructions | User commands and extensions |
share | Session sharing preference |
autoupdate | Update preference |
enabled_providers, disabled_providers | Available provider restrictions |
model, small_model, default_agent | Default model and agent choices |
agent, provider | User agent and provider configuration |
mcp | Connected MCP servers |
formatter, lsp | Formatting and language support |
permission | Allow, 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,blacklistmodels.<modelID>overridesmodels.<modelID>.variants.<name>.disabledoptions.apiKeyoptions.baseURLoptions.enterpriseUrloptions.setCacheKeyoptions.timeout(numberorfalse)
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 acommandarray (executable first, arguments after it), optionalenvironment,enabled, andtimeouttype: "remote"withurl, optionalheaders, optionaloauth
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-> usesharemode-> useagenttools-> usepermissionagent.maxSteps-> useagent.steps