Documentation Index
Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
Use this file to discover all available pages before exploring further.
The MurmurService gRPC API is the backend for the CLI, dashboard, and MCP server. It provides complete programmatic control over agents, catalog resources, pools, sessions, and events.
Architecture
The API server (murmur-api) runs on Google Kubernetes Engine (GKE) and exposes a gRPC interface:
CLI (murmur) Dashboard (murmur-ui) Agent VM (MCP)
↓ gRPC/TLS ↓ gRPC-web ↓ gRPC/TLS
└───────────────────────┼───────────────────────────┘
↓ Envoy (gRPC-web → gRPC)
murmur-api (GKE)
↓
Orchestration / GCS / KMS
- CLI — connects directly via gRPC with TLS
- Dashboard — connects via gRPC-web through an Envoy proxy (required for browser compatibility)
- Agent VMs — the MCP server connects via gRPC with TLS using the agent’s service token
TLS is enabled by default for all connections.
Authentication
Every API request must be authenticated. Three authentication methods are supported:
| Method | Used by | Token source |
|---|
| Identity token | CLI, MCP (local) | GitHub OAuth → murmur login |
| Session cookie | Dashboard | GitHub OAuth → ECIES P-256 encrypted cookie |
| Service token | Agent VMs | Issued by control plane at VM boot |
RPC categories
The API exposes over 80 RPCs organized into the following categories.
Agent lifecycle
RPCs for creating, managing, and controlling agents:
| RPC | Description |
|---|
Spawn | Create a new agent task with full configuration |
QueueAdd | Send a follow-up message to a running agent |
Kill | Cancel an agent and its entire subtree |
Sleep | Put a running agent to sleep (idle state) |
Wake | Wake a sleeping agent |
StopTurn | Interrupt the agent’s current turn |
Rekey | Refresh an agent’s credentials without interrupting work |
ClearQueue | Discard all queued follow-ups for an agent |
Queries
RPCs for reading agent and tenant state:
| RPC | Description |
|---|
Status | Get an agent’s current state, progress, PRs, and cost |
List | List agents with optional filters (developer, all, workspace) |
Tree | Get the full agent hierarchy as a tree structure |
Wait | Block until an agent reaches a target phase |
WhoAmI | Return the caller’s identity and permissions |
ListTenants | List tenants the caller has access to |
ResolveVM | Look up which agent is running on a specific VM |
Streaming
Server-streaming RPCs that push real-time updates:
| RPC | Type | Description |
|---|
WatchTree | Server stream | Stream agent tree hierarchy with live updates |
WatchAgent | Server stream | Stream a single agent’s state changes |
StreamSessionEvents | Server stream | Stream live Claude Code session output |
StreamTelemetry | Server stream | Stream cost, token, and performance metrics |
StreamLogs | Server stream | Stream VM-level logs |
SessionChannel | Bidirectional stream | Push/receive channel events (used by MCP server) |
Catalog CRUD
RPCs for managing catalog resources:
| RPC | Description |
|---|
GetResource | Read a single resource by kind and name |
SetResource | Create or update a resource |
ListResources | List all resources of a kind |
DeleteResource | Delete a resource (blocked if referenced) |
DescribeKinds | Get schema information for all resource kinds |
GetResourceHistory | Get version history for a resource |
RevertResource | Revert a resource to a previous generation |
PatchResource | Partial update of resource fields |
Pool management
RPCs for managing the VM pool:
| RPC | Description |
|---|
EnsurePool | Ensure the pool meets minimum capacity |
PoolStatus | Get current pool state: total, available, assigned VMs |
PoolFlush | Drain and recreate the pool |
Bake (image building)
RPCs for building custom VM images:
| RPC | Description |
|---|
BakeRecipe | Start an image build from a recipe |
GetBake | Get the status of a bake job |
ListBakes | List all bake jobs |
WatchBake | Server stream — watch a bake job’s progress in real time |
Subscriptions
RPCs for managing event subscriptions:
| RPC | Description |
|---|
AddSubscription | Subscribe to events for a repository or pattern |
RemoveSubscription | Remove an event subscription |
FlushSubscriptions | Remove all subscriptions |
ListSubscriptions | List active subscriptions |
Tasks
RPCs for managing agent task checklists:
| RPC | Description |
|---|
TaskCreate | Create a new task in an agent’s checklist |
TaskUpdate | Update a task’s status, description, or dependencies |
TaskList | List all tasks for an agent |
TaskGet | Get a single task by ID |
Storage proxy
RPCs that proxy storage operations through the API server (agents cannot access GCS directly):
| RPC | Description |
|---|
PersistSession | Save session state to storage |
RestoreSession | Restore session state from storage |
UploadPublic | Upload a file to the public storage bucket and return its URL |
Proto packages
The API is defined across several Protocol Buffer packages:
| Package | Description |
|---|
murmur.api.v1 | Main API service definition and common types |
murmur.agent.v1 | Agent-specific types (status, phase, config) |
murmur.authz.v1 | Authorization types (permissions, roles, grants) |
murmur.workflow.v1 | Agent orchestration types |
murmur.session.v1 | Session types (events, telemetry, channel) |
murmur.port.v1 | Port forwarding types |
murmur.vm.v1 | VM lifecycle types |
murmur.control.v1 | Control plane types (internal) |
Error handling
The API uses standard gRPC status codes:
| Code | Meaning |
|---|
OK (0) | Success |
NOT_FOUND (5) | Resource or agent does not exist |
ALREADY_EXISTS (6) | Resource or agent already exists (e.g. duplicate spawn) |
PERMISSION_DENIED (7) | Caller lacks required permissions |
FAILED_PRECONDITION (9) | Operation cannot be performed in current state (e.g. kill an already-dead agent) |
UNAUTHENTICATED (16) | Missing or invalid authentication token |
RESOURCE_EXHAUSTED (8) | Pool at capacity, rate limited |
INVALID_ARGUMENT (3) | Malformed request |
Rate limiting
The API enforces per-tenant rate limits to prevent abuse. Limits are generous for normal usage patterns. If you hit rate limits, the API returns RESOURCE_EXHAUSTED with a Retry-After header indicating when to retry.
Streaming RPCs are not rate-limited per message — they are limited by the number of concurrent streams per tenant.
