System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Coral provides a single Model Context Protocol (MCP) server that aggregates multiple services for AI agents. It acts as a secure intermediary that manages credentials, enforces usage policies, and executes agent-provided TypeScript programs in an isolated sandbox.
The system consists of three primary layers: the MCP Server (interface for agents), the Coral UI (management interface for users), and the Sandboxed Runtime (execution environment).
Sources: README.md:3-13, README.md:46-55
High-Level Component Structure
Coral organizes its functionality into distinct modules to maintain durable boundaries between transport, domain logic, and presentation.
This diagram illustrates the relationship between external actors, the internal Coral management system, and the external services Coral orchestrates.
Sources: README.md:46-55, AGENTS.md:16-25
Execution Model
Coral executes agent tasks through "Runs." A Run Owner coordinates each Run, managing its state, events, and timers in memory before committing them as chunks to the database.
Sandboxed Program Execution
Agents submit TypeScript async-function bodies to the exec tool. Coral compiles and runs these programs in a V8-based sandbox.
- Isolaton: Programs have no direct network access, no imports, and no access to secrets.
- Functionality: Programs interact with the system via the
coralnamespace (e.g.,coral.providers,coral.functions). - Error Handling: If a call fails to produce a declared success, Coral throws a
coral.OperationError.
Sources: README.md:6-10, crates/coral-mcp/src/arguments.rs:163-172, crates/coral-v8/src/js/compiler/typescript_environment.js:15-38
Run Lifecycle and Persistence
Domain behavior is separated from transport and presentation adapters.
- Transaction Choreography: Domain code owns transactions; repository facets join them to ensure atomicity.
- Dispatch Fence: A gate that performs shared rechecks of fact rows (Workspace, Provider, Policy) before dispatching an invocation.
- Worker Leases: Ensure that only one process holds ownership of a live Run at a time.
Sources: AGENTS.md:31-48, AGENTS.md:82-90
Model Context Protocol (MCP) Interface
The coral-mcp crate defines the tools available to AI agents.
| Tool | Description | Mutation |
|---|---|---|
start_task | Begins a unit of user work. | Yes |
search | Searches visible operations and saved functions. | No (Read-only) |
describe | Retrieves TypeScript signatures and input requirements. | No (Read-only) |
exec | Starts a new Program Run from TypeScript source. | Yes |
wait | Observes log emissions and state changes of a Run. | No (Read-only) |
save_function | Persists a successful program as a reusable function. | Yes |
Sources: crates/coral-mcp/src/arguments.rs:206-250
User Interface Architecture (Reef & Wax)
The Coral UI, named Reef, is built using React Router and enforces strict architectural invariants via automated tests.
Presentation Boundaries
- Data Fetching: Presentation modules (components and views) must not fetch data. Data reaches them through route loaders or fetchers.
- Wax Primitives: Reusable visual behavior and styling reside in the
waxmodule. App-specific layouts compose Wax primitives rather than defining parallel controls. - Credential Safety: Credential entry is restricted to the
Wax.CredentialInputcomponent and must bypass standard React RouterformDatato ensure security.
Sources: AGENTS.md:112-125, apps/reef/app/tests/architecture.test.ts:15-20, apps/reef/app/tests/architecture.test.ts:124-142
Routing and Middleware
Reef uses server-side loaders for initial data and resource routes for live updates via streaming connections.
This flow ensures initial page loads are fast while supporting real-time activity monitoring.
Sources: apps/reef/app/tests/architecture.test.ts:251-260, AGENTS.md:126-132
Desktop Application Supervisor
The desktop application is an Electron-based wrapper that manages the lifecycle of the Coral runtime and the web server.
- Process Roles: The supervisor tracks "runtime" (Coral core logic) and "web server" (Reef) roles.
- State Management: The app detects port conflicts, crashed processes, and data locks (if another runtime instance is active).
- Environment Handling: Configuration is read from the process environment only at bootstrap and passed explicitly to domain code.
Sources: apps/desktop/src/main/local-pages.ts:40-58, apps/desktop/electron-builder.config.ts:31-50, AGENTS.md:19-21
Persistence and Migrations
Coral supports both SQLite and Postgres.
- Schema Portability: All migrations live in
crates/coral-db/migrationsand must be compatible with both database backends. - Integrity: Migrations on the
mainbranch are never deleted or modified to ensure that existing databases can always boot. - FTS Support: Features like Full Text Search (FTS5) are checked at boot time before the migration chain runs.
Sources: AGENTS.md:95-108