Agent & Workspace Management
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- README.md
- apps/reef/app/views/management/workspace-overview.tsx
- apps/reef/app/lib/management.server.ts
- apps/reef/app/lib/management-views.server.ts
- crates/coral-grpc/src/grpc/workspaces.rs
- crates/coral-grpc/proto/coral/management/v1/workspace.proto
- apps/reef/app/views/management/agent-settings-page.tsx
- apps/reef/app/views/management/agent-activity-page.tsx
Agent & Workspace Management provides the administrative infrastructure for organizing services, credentials, and automated programs within the Coral platform. A Workspace serves as a secure container for providers, policies, and agents, while Agents act as automated entities capable of executing TypeScript programs in a sandboxed environment.
Sources: README.md:3-9, crates/coral-grpc/proto/coral/management/v1/workspace.proto:3-16
Workspace Administration
Workspaces manage the lifecycle of configurations and ensure data isolation between different teams or projects. Every Workspace has a lifecycle state that determines its ability to accept new work or configurations.
Workspace Lifecycle and States
A Workspace exists in one of two primary active states defined by the system:
- Active: Accepts configuration changes and new program executions under current authority.
- Archived: Rejects configuration and new work. It stops future dispatch without deleting retained history. Only a Workspace Owner can restore an archived workspace.
Sources: crates/coral-grpc/proto/coral/management/v1/workspace.proto:20-28, apps/reef/app/views/management/agent-activity-page.tsx:32-37, apps/reef/app/lib/management-views.server.ts:31-35
Workspace Membership Roles
User authority within a workspace is governed by specific roles:
- Owner: Can administer the workspace, rename it, archive/restore it, and manage members or agents.
- Member: Can use the workspace and view its contents but lacks administrative authority.
Sources: crates/coral-grpc/proto/coral/management/v1/workspace.proto:31-38, apps/reef/app/views/management/workspace-overview.tsx:64-74
This diagram represents the Workspace state machine and the actions permitted in each state.
Sources: crates/coral-grpc/proto/coral/management/v1/workspace.proto:6-14, crates/coral-grpc/src/grpc/workspaces.rs:240-275
Agent Management
Agents are independent entities used for automations that run without direct human intervention. They utilize Model Context Protocol (MCP) to communicate with clients and execute sandboxed programs.
Agent Components and Security
Agents are identified by a unique resource name (workspaces/{workspace}/agents/{agent}) and utilize API keys for authentication.
- Registration: Every agent has a registration record holding its API key, access status, and expiration date.
- Access Blockers: Access can be prevented by several factors, including the agent being disabled, the workspace being archived, API suspension, or credential expiration.
- Sandboxing: Programs run in an isolated environment with no network access, no imports, and no access to the user's raw credentials.
Sources: AGENTS.md:73-85, apps/reef/app/lib/management.server.ts:108-112, apps/reef/app/views/management/agent-settings-page.tsx:84-110
Agent Configuration Table
| Field | Description | Source |
|---|---|---|
displayName | Mutable human label for the agent. | apps/reef/app/lib/management-views.server.ts:54 |
state | enabled (allows runs) or disabled (blocks new runs). | apps/reef/app/lib/management-views.server.ts:58-61 |
expiration | UTC timestamp after which access is immediately blocked. | apps/reef/app/views/management/agent-settings-page.tsx:135-144 |
accessBlockers | List of reasons why the agent is currently unable to run. | apps/reef/app/lib/management-views.server.ts:65-71 |
Data Flow and Persistence
Coral implements a strict persistence model to ensure atomicity and consistency across Workspace and Agent operations.
Persistence Rules
- Ownership Match: Every externally influenced read or write must match both the Workspace ID and the entity identity, even if the entity ID is globally unique.
- Run Owners: Nonterminal runs are written only through their designated Run Owner to prevent data races and ensure timer-based events (like timeouts) are handled in a single mailbox order.
- Database Constraints: The system uses a shared migration chain across SQLite and Postgres, strictly avoiding
IF NOT EXISTSto ensure schema drift is detected and failed early.
Sources: AGENTS.md:52-125, crates/coral-grpc/src/grpc/workspaces.rs:356-385
API Communication Sequence
The following sequence illustrates the interaction between the Reef UI, gRPC management services, and the persistence layer when creating an agent.
This diagram shows the multi-step insertion process required for agent provisioning.
Sources: apps/reef/app/views/management/workspace-overview.tsx:82-94, apps/reef/app/lib/management.server.ts:31-48, crates/coral-grpc/src/grpc/workspaces.rs:188-212
Connectivity and MCP Integration
Workspaces expose a canonical, non-secret "Streamable HTTP" endpoint used by MCP clients (such as Claude Code or Codex) to connect.
- Endpoint Format:
{origin}/workspaces/{id}/mcp. - Authentication:
- Humans: Sign in via browser/OAuth to obtain session tokens.
- Agents: Use a
Bearer <AGENT_API_KEY>authorization header with every request.
- Client Configuration: Coral provides automated setup snippets for common clients, including terminal commands for Claude Code and TOML configuration for Codex.
Sources: README.md:46-52, crates/coral-grpc/proto/coral/management/v1/workspace.proto:106, apps/reef/app/views/management/quick-start.tsx:39-65
Conclusion
Agent & Workspace Management forms the backbone of the Coral platform's security and organizational model. By isolating resources within Workspaces and enforcing strict identity matching for Agents, the system ensures that automated programs operate within defined boundaries while maintaining a full audit trail of activity and policy enforcement.