Architecture

Architecture

OpenPhoenix is one Rust crate with two binaries. phoenix is the runtime and command-line interface. phoenix-e2e is an isolated end-to-end test driver. Shared behavior is implemented in runtime modules rather than duplicated in provider or channel adapters.

Runtime flow

1. The CLI selects interactive chat, one-shot work, service mode, or an operational command.
2. Configuration resolves public settings and credential references. Credentials are supplied from the host environment, OAuth state, or the sealed store.
3. A provider adapter translates normalized messages, tools, reasoning controls, and usage into the selected wire protocol.
4. The agent loop applies context budgeting, compaction, retries, fallback, loop detection, tool policy, approvals, and output redaction.
5. A channel adapter maps normalized inbound and outbound events to a terminal, chat network, HTTP, WebSocket, web UI, or ACP client.
6. Optional state modules persist only the mode-specific data the operator enabled.

Major boundaries

Boundary	Main responsibility
Agent and providers	Turns, tool calls, model capabilities, streaming, usage, and fallback
Colab and debate	Two-seat planning, discussion, concurrent work, peer review, quota delegation, and recovery
Tools and security	Workspace jail, command gate, approvals, network policy, output limits, redaction, and loop detection
Channels	Telegram, WhatsApp, Discord, Slack, Signal, IRC, Matrix, Mattermost, and iMessage adapters
Gateway	HTTP API, WebSocket, web UI, webhooks, canvas, authentication, rate limiting, and security headers
State	Sessions, readable memory, encrypted secrets, audit records, tasks, boards, commitments, and fleet cells
Automation	Cron jobs, heartbeat, dreaming, hooks, background work, and service lifecycle
Extensions	Skills, MCP servers, claws, browser automation, media, audio, nodes, and devices

Design properties

Optional integrations default off. Empty channel allowlists refuse all senders. Network tools reject private and special-use destinations unless explicitly allowed. File tools remain in the configured workspace unless that boundary is explicitly relaxed. Model and client adapters share these controls rather than owning different security behavior.

The dependency set is intentionally small and Rust unsafe_code is forbidden by the crate configuration. See Security, Configuration, and Building.