Configuration guide

One runtime.
Clear settings.

Use this map to see which settings are shared, which belong to one workspace, and which only last for an ACP session or server process.

Configuration architecture

Arabica has one shared CLI/ACP configuration, a few narrower scopes, and a separate environment-based configuration for the HTTP server.

Three different meanings of “policy”. A Blend policy routes model aliases; runner permissions decide whether tools can run; compaction strategy controls runtime memory retention. They are configured and used separately.

Project AGENTS.md files are instructions sent to the model, not settings in config.toml. They apply to CLI and ACP workspaces. Arabica Desktop is an ACP client: its Settings item lists and forms edit providers, model aliases, routing policies, MCP servers, and skill directories in the shared user file. Valid changes save automatically; session selectors use options reported by the ACP host.

Quick start

Create a named provider, one model alias, and a default policy. Enter the API key separately so it is not written into the TOML file.

mkdir -p ~/.arabica
cat > ~/.arabica/config.toml <<'EOF'
[providers.openai]
api_type = "open_ai_responses"
base_url = "https://api.openai.com/v1"
api_key_env = "ARABICA_PROVIDER_OPENAI_API_KEY"

[models.default]
provider = "openai"
model_id = "your-model-id"

[blend]
default_policy = "coding"

[blend.policies.coding]
version = 1
default_model = "default"
EOF
export ARABICA_PROVIDER_OPENAI_API_KEY="your-api-key"
arabica config
arabica -p "Explain this workspace"

Use the provider’s actual API dialect, endpoint, model ID, and key. See the CLI guide for current supported API types and ACP setup.

User configuration

The shared file is $ARABICA_HOME/config.toml; when ARABICA_HOME is unset, that means ~/.arabica/config.toml. CLI and ACP load the same providers, model aliases, Blend policies, and user-declared MCP servers.

[providers.openai]
api_type = "open_ai_responses"
base_url = "https://api.openai.com/v1"
api_key_env = "ARABICA_PROVIDER_OPENAI_API_KEY"
max_tokens = 8192
reasoning_effort = "high"
request_timeout_secs = 180

[providers.anthropic]
api_type = "anthropic_messages"
base_url = "https://api.anthropic.com/v1"
api_key_env = "ARABICA_PROVIDER_ANTHROPIC_API_KEY"
max_tokens = 8192
thinking = "high"
anthropic_cache_static_prefix = true

[models.fast]
provider = "openai"
model_id = "your-fast-model"

[models.strong]
provider = "anthropic"
model_id = "your-strong-model"

[blend]
default_policy = "coding"

[blend.policies.coding]
version = 1
default_model = "fast"
after_tool_success = "fast"
after_tool_error = "strong"
recovery_model = "strong"
recovery_after_no_progress_steps = 2
minimum_model_dwell_steps = 2
tool_call_capable_models = ["fast", "strong"]
typed_completion_capable_models = ["fast"]

[blend.policies.review]
version = 1
default_model = "strong"
after_tool_error = "strong"
Section / fieldWhat it controls
[providers.<name>]API type, base URL, key source, token limit, thinking/reasoning and provider-specific request behavior. Use either thinking or reasoning_effort for one provider, not both.
[models.<alias>]Stable name used in routing and selectors; points to a provider and its real model_id.
[blend]default_policy picks which named policy is active by default.
[blend.policies.<id>]Default alias, optional after-tool and recovery routes, minimum dwell, and model capability declarations. Every alias must exist in [models.*].

Provider options are optional unless your endpoint requires them. anthropic_cache_static_prefix is specific to Anthropic. thinking values depend on the API type; unsupported settings are rejected during configuration resolution.

Workspace preferences

Arabica stores model preferences separately for each workspace under $ARABICA_HOME/workspaces/<workspace-id>/config.toml. The workspace ID is derived from its directory path.

model_alias = "fast"
model = "your-model-id-override"
thinking = "high"

All three fields are optional: model_alias chooses the default alias; model overrides the provider model ID for that workspace; and thinking sets its default thinking preference. Workspace settings contain no credentials or provider endpoints. Use arabica config to inspect the resolved setup and paths.

ACP session choices

On new and restored sessions, ACP reports the model aliases and applicable controls supported by the active host configuration.

  • Model: selects a configured alias for the current session.
  • Policy: appears when multiple named Blend policies are configured; selects which policy the current session uses.
  • Thinking: appears only when the selected API type supports a thinking control.
  • Session mode: Arabica currently reports no session-mode selector.

Changing these ACP options changes the active session, not the global TOML or saved workspace preference. Policy route details stay in the host configuration; an ACP client only needs to present the policy choices reported by the host.

Credential sources

For a provider named openai, the default environment variable is ARABICA_PROVIDER_OPENAI_API_KEY. Set api_key_env to use another variable. Alternatively, enter a key with arabica auth login; it is stored in $ARABICA_HOME/auth.json with owner-only permissions.

Credential lookup prefers the provider’s configured environment variable, then an inline api_key if present, with the saved auth key as a fallback for the default provider. Avoid putting API keys in TOML. If you do store one there, restrict access to the file (macOS/Linux: chmod 600 ~/.arabica/config.toml).

Use arabica auth status to inspect the active credential source without displaying the key; arabica auth logout removes the saved auth key.

Tools and MCP

Tool permission is separate from model routing. ACP uses permission requests when a tool call needs approval; the terminal exposes options such as --read-only and --allow-shell. The HTTP server has its own tool-root setting.

User MCP servers belong in the shared TOML and are available to terminal and ACP. An ACP client can also pass MCP servers for a session; its entry takes precedence when a server name matches.

[[mcp]]
name = "local-docs"
command = "/absolute/path/to/docs-mcp"
args = ["--verbose"]

[mcp.env]
DOCS_TOKEN = "your-token"

[[mcp]]
name = "remote-search"
url = "https://mcp.example.test/mcp"

[mcp.headers]
Authorization = "Bearer your-token"

Each server uses exactly one transport: local command (stdio) or HTTP url. Store secrets in environment/header entries only when needed, and keep the config file private.

Both transports prefer the stateless MCP 2026-07-28 protocol and automatically fall back to the legacy initialization handshake for older servers. Modern requests carry their protocol version, client identity, and capabilities independently; HTTP requests do not need an MCP session ID. The same configuration works in the desktop app, terminal, and ACP clients.

Use headers for authentication and application-specific headers. Protocol headers such as MCP-Protocol-Version, Mcp-Method, Mcp-Name, and Mcp-Param-* are generated automatically and cannot be overridden. HTTP redirects are limited to same-origin 307/308 responses. Optional capabilities such as MCP Apps, Tasks, and elicitation are not enabled.

For tokens that expire or rotate, replace the static Authorization header with an [mcp.auth] table. Arabica then resolves the token for every request and refreshes it on expiry or after a single 401, without restarting the session. It never falls back to an unauthenticated request.

[[mcp]]
name = "remote-search"
url = "https://mcp.example.test/mcp"

[mcp.auth]
mode = "oauth"        # authorize once: arabica mcp login remote-search
binding = "work"      # optional; separate grants per binding

# or: mode = "command" with command = ["/absolute/path/to/token-helper"]

ACP clients can declare the same modes, plus broker, in the server's _meta under arabica.auth. In broker mode, the client answers _arabica/mcp/credential requests and keeps the refresh tokens. See dynamic MCP authentication for the contract and the retry rules.

HTTP server configuration

arabica-server uses process environment variables rather than the CLI/ACP user TOML. Set the required provider catalog and model aliases, then optional routing and runtime settings.

Environment variablePurpose
ARABICA__PORTHTTP port; default 4096.
ARABICA__PROVIDERS_JSONRequired provider definitions, keyed by provider name; includes endpoint/API type and request options.
ARABICA__BLEND_MODELS_JSONRequired alias-to-provider/model-ID catalog.
ARABICA__BLEND_DEFAULTDefault model alias.
ARABICA__BLEND_AFTER_TOOL_SUCCESS / _AFTER_TOOL_ERROROptional alias routes after tool success or error.
ARABICA__BLEND_RECOVERY_MODEL / _RECOVERY_AFTER_NO_PROGRESS_STEPSOptional recovery alias and no-progress threshold.
ARABICA__BLEND_MINIMUM_MODEL_DWELL_STEPSMinimum calls before ordinary model switching.
ARABICA__BLEND_TOOL_CALL_MODELS / _TYPED_COMPLETION_MODELSComma-separated aliases with the corresponding declared capability.
ARABICA__BLEND_POLICY_ID / _POLICY_VERSIONIdentity recorded for the active routing policy.
ARABICA__TOOL_ROOTFilesystem root exposed to the local runner; defaults to the current directory.
ARABICA__COMPACTION_STRATEGYMemory retention strategy: file_backed_gc (default), pointer_gc, or disabled.
ARABICA__ARCHIVE_ROOTDirectory for lossless compaction archives.
COMPACTION_EFFORTCompaction cost threshold; the legacy PGC_EFFORT is also accepted.

Provider keys are supplied through the corresponding provider key environment variable. The HTTP server also reads a local .env file; CLI configuration intentionally does not.

Which value wins?

Scope matters. A startup flag or environment override can temporarily change the default model setup; ACP selectors only affect the current session.

ValueResolution order (highest priority first)
Default model ID--model → workspace model → ARABICA__MODEL → configured alias model ID
API type / base URLCLI flag → matching ARABICA__API_TYPE / ARABICA__BASE_URL → provider entry
API keyprovider key environment variable → inline provider key → saved auth fallback for the default provider
Default model alias / policyworkspace alias preference can change the default alias; [blend].default_policy selects the default named policy
ThinkingACP session choice → workspace preference → provider default → off

To validate and inspect the effective CLI/ACP setup, run arabica config. Start with the user config; add workspace preferences only when you want a project-specific default.