Introduction to Coral
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 connects AI agents to multiple services using your credentials and rules. Agents write short TypeScript programs which Coral executes in an isolated sandbox, automatically adding required tokens and enforcing user-defined policies for every service call.
The system replaces the need for multiple MCP servers and manual token management. It optimizes agent interaction by allowing agents to search for specific operations and execute multi-step programs in a single round trip, reducing the context window size and prompt complexity.
Sources: README.md:5-20, README.md:65-75
System Architecture
Coral consists of three primary components: the Coral MCP Server, the Coral UI (Reef), and the Sandboxed Program Run environment.
The diagram shows the flow of requests from the agent through the Coral MCP server, which triggers sandboxed runs validated by user policy and credentials before reaching external services.
Sources: README.md:63-75
Core Components
| Component | Description |
|---|---|
| Coral MCP Server | Handles agent requests for discovery (searching operations) and execution of programs. |
| Reef (Coral UI) | The shared human interface for managing providers, setting policies, and approving requested actions. |
| Sandboxed Run | An isolated V8 environment where TypeScript programs run without network or filesystem access. |
| Gatekeeper | Manages credentials and enforces user-defined policies (Allow, Approval Required, Disabled). |
Sources: README.md:15-32, README.md:65-75, apps/reef/README.md:3-8
Program Execution and Sandboxing
Coral executes agent-written TypeScript programs using a V8-based runtime. The environment is strictly isolated to prevent unauthorized access and data leaks.
Sandbox Constraints
- No Network Access: Programs cannot make direct outbound HTTP calls; they must use
coral.providers. - No Imports: Programs cannot use
importorrequireto load external modules. - No Credentials: Programs never see raw tokens; Coral injects these during the final call to the service provider.
- Resource Limits: The execution environment enforces isolate limits to prevent non-cooperative or infinite loops.
Sources: README.md:20-22, crates/coral-v8/tests/program_runtime.rs:59-70, crates/coral-v8/tests/program_runtime.rs:555-580
Execution Flow
- Search: The agent queries available operations via the MCP server.
- Compose: The agent writes a TypeScript program calling these operations.
- Execute: Coral compiles and runs the program in V8.
- Policy Check: Each call to
coral.providerstriggers a policy check. - Approval: If a call requires approval, the run pauses until the user acts in the UI.
Sources: README.md:15-20, README.md:88-92, AGENTS.md:73-85
Deployment Models
Coral supports multiple deployment strategies, ranging from local desktop use to team-hosted servers.
Coral Desktop
Coral Desktop supervises local processes and provides an Electron-based interface. It manages:
- The
coralruntime as a child process. - The Reef server in an Electron utility process.
- Automatic port allocation for MCP, Reef, and gRPC listeners.
Sources: apps/desktop/README.md:3-20
Self-Hosted Server
Teams can run a shared Coral server. This requires configuring:
- Database: Supports SQLite (default) and Postgres.
- Authentication: Reef can be configured for hosted authentication using
CORAL_WEB_AUTH_MODE=required. - Listeners: Distinct listeners for MCP (HTTP), gRPC, and Auth.
Sources: README.md:35-40, apps/reef/README.md:20-45, apps/desktop/README.md:225-240
Persistence and Identity
Coral uses stable, human-readable identifiers for tasks and program runs. These are generated by joining four random words (e.g., height-word-database-library).
The relationship shows how workspaces act as the primary boundary for data, containing providers, accounts, and recorded execution runs.
Sources: crates/coral-identifier/README.md:3-6, AGENTS.md:105-110
Data Integrity Rules
- Workspace Isolation: Every read or write must match both the Workspace ID and the Entity ID, ensuring multi-tenant safety.
- Transaction Management: Domain code manages transaction choreography; repository layers handle row locking and atomicity.
- Audit Log: Every program run and the resulting service calls are recorded for review in the Coral UI.
Sources: README.md:26-30, AGENTS.md:30-45, AGENTS.md:105-110
Summary
Coral centralizes agent-to-service interactions by providing a secure, policy-governed execution environment. By running agent code in a sandbox and managing credentials centrally, it reduces security risks and optimizes the context window for AI models. Users retain full control via the Reef UI through granular policy settings and manual approval gates.
Sources: README.md:5-32, README.md:88-95