Arabica
Website · Configuration · Apache-2.0 license
Arabica is a headless AI-agent runtime written in Rust. The project defines a canonical command/event protocol, session lifecycle, model-provider boundary, tool runner, memory policies, and an HTTP/SSE host.
Status: active development (
0.1.1). A first native macOS client lives inapps/arabica-desktop. The Rust runtime remains headless.
Architecture
The Cargo workspace is split into small crates with explicit ownership:
| Crate | Responsibility |
|---|---|
arabica-model |
Shared model-facing content and tool types |
arabica-protocol |
Canonical commands, events, identifiers, and schema |
arabica-provider |
Model-provider abstraction and API implementations |
arabica-runner |
Local tool execution boundary |
arabica-runner-remote |
Loop–Runner Protocol: remote runner client and runner host over WebSocket + mTLS |
arabica-runtime |
Agent loop, long memory, and short-memory projection |
arabica-session |
Session identity, sequencing, history, and lifecycle |
arabica-server |
Axum HTTP and SSE protocol host |
arabica-cli |
Stdio composition host: arabica acp (Agent Client Protocol) and arabica -p (one-shot) |
The runtime is protocol-first: clients submit a CommandEnvelope, the session
layer validates and sequences the operation, and the runtime emits canonical
EventEnvelope values. The HTTP host exposes the same contract without adding
client-specific state.
The macOS desktop client uses SwiftUI and AppKit. It launches the CLI's ACP agent as a bundled process and presents conversations, live updates, and tool permission requests. Build instructions are in its README.
HTTP API
arabica-server currently exposes:
| Endpoint | Purpose |
|---|---|
GET /health |
Liveness check |
GET /v1/schema |
Canonical protocol schema |
POST /v1/commands |
Submit a command and receive emitted events |
GET /v1/events |
Subscribe to events over SSE |
The server listens on 127.0.0.1:4096 by default.
Requirements
- Rust 1.88 or newer
- A supported model-provider endpoint when running the HTTP server or the CLI
Install the CLI
On macOS or Linux, download the latest release with curl. The installer selects
the matching CPU architecture, verifies the published SHA-256 checksum, and
installs arabica to ~/.local/bin by default:
Set ARABICA_INSTALL_DIR to choose another directory or
ARABICA_VERSION=v0.1.1 to pin a release. Windows ZIP archives are on
GitHub Releases.
With Rust 1.88 or newer, install the published package from crates.io:
The package is named arabica-cli; its executable is arabica. See the
configuration guide
for provider credentials, precedence, Blend routing, MCP tools, and server
settings.
Standalone releases support arabica update and daily background updates during
interactive use. Use arabica update --auto off to opt out. The macOS app has
Check for Updates… and Settings → Updates, including automatic download
and installation on quit. See software updates for package
manager support, signed downloads, and the one-time upgrade from older versions.
Build and Test
Run the Server
Configure named provider and model candidates. Keys stay in the environment:
Then start the host:
Session persistence
CLI, interactive chat, ACP, and the production HTTP server store session metadata
and ordered events in $ARABICA_HOME/sessions.sqlite3 (default: ~/.arabica).
The backend-independent SessionStore and SessionWriter ports and shared
metadata types live in arabica-session. arabica-adapters::SqliteSessionRepository
implements the repository port; CLI and server code select it during composition
and use IDs through the port thereafter. SessionWriter keeps exclusive ownership
until its final handle (including observer handles) is dropped.
SQLite uses WAL and full synchronous transactions. Session ownership locks remain
per session, preventing two processes from resuming the same session concurrently.
Legacy sessions/<workspace>/<session>.jsonl files are imported transactionally
on first access and retained unchanged. After import, SQLite is authoritative;
older binaries must not be used to continue imported sessions.
Titles default to the first non-empty user message (up to 80 characters) and are returned in ACP session listings. To rename an inactive session in the current workspace, run:
The HTTP server restores sessions for its canonical tool root on startup; the
embedding AppState::default() remains ephemeral unless with_session_store is
called with an Arc<dyn SessionStore> and a tool root. The existing snapshot restore API accepts root sessions only; persisted
forks currently cause an explicit startup restore error rather than losing their
inherited history. Command deduplication remains in memory across a process lifetime.
When backing up an active database, use SQLite's backup facilities so committed
WAL data is included.
CLI model blend
The CLI reads ~/.arabica/config.toml. Define reusable provider settings under [providers.<name>]; each [models.<alias>] selects a provider and model ID. Blend routes continue to refer to aliases. Provider API keys come from the configured api_key_env, or by default from ARABICA_PROVIDER_<NAME>_API_KEY (provider name uppercased with non-alphanumeric characters replaced by underscores).
ACP tool permissions can be adjusted in the same file. Rules are allow, ask, or deny; tool-specific rules override default. Without this section, read-only tools remain allowed and other tools ask before running.
[]
= "ask"
[]
= "deny"
= "allow"
= "ask"
[[]]
= "shell"
= "command"
= "(^|[;&|[:space:]])rm([[:space:]]|$)"
= "deny"
Argument rules are checked in order before the per-tool and default rules. parameter accepts a dot-separated path into the tool arguments (for example command or options.path); * matches the serialized argument object. pattern is a Rust regular expression matched against that parameter's string value (or JSON representation for non-string values).
[]
= "open_ai_responses"
= "https://api.openai.com/v1"
= "ARABICA_PROVIDER_OPENAI_API_KEY"
= 8192
= "high"
[]
= "anthropic_messages"
= "https://api.anthropic.com/v1"
= "ARABICA_PROVIDER_ANTHROPIC_API_KEY"
= 8192
= 180
= true
[]
= "openai"
= "gpt-4.1-mini"
[]
= "anthropic"
= "claude-sonnet-4-5"
[]
= "coding"
[]
= 1
= "fast"
= "fast"
= "strong"
= 2
= "strong"
= 2
= ["fast", "strong"]
= ["fast"]
[[]]
= "sed-shell-route"
= "strong"
= { = "event_trace_regex", = "toolcall\\.shell\\.sed.*toolresult\\.shell\\.success" }
[]
= 1
= "strong"
= "strong"
= 2
The CLI validates every provider reference, alias, credential source, and API-specific setting at startup. A TOML api_key is accepted as a fallback to the environment variable; a config file containing keys must be owner-only (chmod 600). arabica auth login remains a saved-key fallback for the default provider. Open-source users can connect through the official Sign in with ChatGPT flow with the one-step command arabica auth chatgpt-login; after authorization, Arabica automatically configures its default model for ChatGPT plan usage. Tokens are saved under $ARABICA_HOME/chatgpt-auth.json with owner-only permissions and refreshed automatically. Blend routing is active in interactive chat, arabica -p, and ACP sessions. ACP exposes configured policy IDs and model aliases as session selectors. Selecting a policy changes the current session's routing rules; selecting a model changes that policy's session default. For one policy, the earlier flat [blend] fields remain accepted.
Example ChatGPT plan provider:
[]
= "chatgpt"
= "open_ai_responses"
[]
= "openai"
= "gpt-6.1-sol"
base_url defaults to https://api.openai.com/v1 for this auth mode and cannot be overridden. Choose a model available to the connected ChatGPT account. Manage the connection with arabica auth chatgpt-status and arabica auth chatgpt-logout.
The desktop composer exposes Default Model, Blend Policy, and Thinking selectors.
Terminal chat offers /model [alias], /policy [name], and /thinking [level];
without an argument, these commands show current selections and available choices.
Selections take effect on the next prompt and are saved for the workspace, with
reasoning effort saved per alias. Startup flags --model-alias, --policy, and
--thinking provide temporary overrides, including in one-shot mode. See the
daily development configuration and
CLI selection rules for planning, repair, and fixed-model routing.
Optional configuration:
For parallel local development, see the worktree setup guide.
ARABICA__PORT: listening port, default4096ARABICA__PROVIDERS_JSON: server provider definitions, keyed by provider nameARABICA__BLEND_MODELS_JSON: server alias entries withproviderandmodel_idARABICA__BLEND_DEFAULT: default alias, defaults to the first alias in sorted orderARABICA__BLEND_AFTER_TOOL_SUCCESS: optional alias for the next call after a successful tool resultARABICA__BLEND_AFTER_TOOL_ERROR: optional alias after a tool errorARABICA__BLEND_RECOVERY_MODEL: optional alias after repeated no-progress steps (threshold defaults to 2 and is set byARABICA__BLEND_RECOVERY_AFTER_NO_PROGRESS_STEPS)ARABICA__BLEND_MINIMUM_MODEL_DWELL_STEPS: minimum consecutive calls to keep a selected model before ordinary routing can switch; error and recovery routes bypass this hold, default1ARABICA__BLEND_TOOL_CALL_MODELS: comma-separated aliases certified for tool callingARABICA__BLEND_TYPED_COMPLETION_MODELS: comma-separated aliases certified for typed terminal completionARABICA__BLEND_POLICY_IDandARABICA__BLEND_POLICY_VERSION: immutable policy identity recorded with each routeARABICA__TOOL_ROOT: root directory available to the local runnerARABICA__COMPACTION_STRATEGY:file_backed_gc(default),pointer_gc, ordisabledARABICA__ARCHIVE_ROOT: local lossless-compaction archive directory, defaulttarget/arabica-runtime-memoryCOMPACTION_EFFORT: minimum expected return over one cache reset; legacyPGC_EFFORTremains accepted
The current server and Harbor benchmark entry points use the atomic local-file archive adapter. SQLite remains available as an explicit Runtime adapter but is not selected by either executable.
Run the CLI
arabica-cli builds a structure binary with two entry points: structure acp (Agent Client Protocol v1 over stdio, for editors like Zed) and
structure -p "task" (one-shot execution). Both read provider-specific key
environment variables and the model configuration from ~/.arabica/config.toml.
See docs/cli.md for flags,
exit codes, and a Zed configuration snippet.
Benchmarks
The Rust short-memory benchmark is a workspace member:
Benchmark inputs, policies, and evidence gates live under
benchmarks/runtime-short-memory/.
Repository Status
The Python service, memory benchmark framework, and Harbor Python orchestration
have been removed. The Rust workspace is the single maintained implementation;
structure-short-memory-benchmark is the single experiment package. JavaScript
fixtures and the CLI proxy remain supporting tools for that package.
Run make check for Rust checks and offline benchmark/proxy tests (Node.js is
required for proxy tests). See benchmarks/README.md for available entry points.
The old Python CLI and import interfaces are no longer available. The former
Python container deployment workflow was removed; tags do not deploy a service.
The paper, reports and frozen protocols preserve historical evidence and may refer to removed runners. They do not establish reproducibility on this commit. Local datasets, experiment outputs and archived binaries remain untouched.
No browser UI, React application, or other frontend is currently maintained.
License
Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE. Contributions are accepted under the same license unless explicitly stated otherwise.
Versioned event trace routes
Use event_trace_v1_regex for newline-delimited canonical event records. Each
record begins with its path followed by |key=value fields. Values and dynamic
path segments use UTF-8 percent encoding; arbitrary arguments and tool output
are excluded. Routes inspect the preceding model step in the current run.
[[]]
= "shell-text-tools"
= "strong"
= 10
= { = "event_trace_v1_regex", = '(?m)^toolcall\.shell\.(sed|grep|rg)\|' }
For trajectories across records, use (?ms) so . includes newlines. Shell
results inherit executable labels through their run and call IDs. Compound or
expanding shell commands receive no executable label. Existing exact-name,
regex-name, kind, and legacy trace routes retain their precedence; recovery and
error handling still take precedence over tool routes. Oversized V1 traces do
not match. This is a routing signal, not a shell authorization mechanism.
Run acceptance and policy campaigns
Terminal runs now include per-run timing and immutable evidence in background
reports. Explicit acceptance specifications provide completion and coverage;
unspecified tasks remain unverified. The desktop evaluation panel displays these
results. Use arabica evaluations runs, score, and compare, or run isolated
real policy trials with the existing benchmark's policy_campaign binary.
See run evaluation for formats and examples.
Image input
The macOS client's paperclip accepts PNG, JPEG, WebP, and GIF images (up to four per message, 5 MiB each). Choose a vision-capable model. ACP advertises the image prompt capability and forwards image bytes through the canonical message and session history to OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or Gemini Generate Content. Ordinary file attachments remain resource links. Image generation and editing are not built-in tools.
The message.send payload and message.accepted event accept an optional
images array of { "media_type": "image/png", "data_base64": "..." } objects.
Omitting it retains the existing text-only wire format. Image bytes are persisted
with the session and sent to the configured provider for their own turn only;
later requests replace them with a short note so request size stays bounded.