Skip to main content

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.

Murmur is designed with the assumption that agent VMs are untrusted. Credentials are encrypted end-to-end, tenants are cryptographically isolated, and the platform enforces strict boundaries between what different components can access.

​
Trust zones

Murmur operates across three distinct trust zones, each with different security properties:

​
Control plane (trusted)

The control plane runs on Google Kubernetes Engine (GKE) and is fully managed by the Murmur platform. It includes:
  • murmur-api — the gRPC API server
  • Control workers — background processes that orchestrate agent lifecycles
  • KMS access — encryption and decryption of tenant data
  • Catalog storage — GCS-backed resource store
The control plane is trusted because it runs platform-managed code in a secured environment with no tenant-supplied code execution.

​
Agent VMs (untrusted)

Agent VMs run tenant code and AI agent sessions. They are treated as untrusted because:
  • They execute arbitrary code (the agent can run any Bash command)
  • They interact with external services (GitHub, package registries, APIs)
  • A compromised agent could attempt lateral movement
Every security decision assumes the VM may be compromised. Credentials are scoped, short-lived, and delivered through secure channels.

​
External events (verified)

External events come from GitHub webhooks, CI systems, and other third-party services. These are signature-verified before processing:
  • GitHub webhooks are validated using HMAC signatures
  • GitHub Actions authenticate via OIDC + Workload Identity Federation
  • All event payloads are validated before being routed to agents

​
Tenant isolation

Each tenant (GitHub organization) is cryptographically isolated from every other tenant:

​
Per-tenant KMS scope

Every tenant has its own Cloud KMS encryption key. This key is used for:
  • Encrypting developer profiles during setup
  • Encrypting tenant secrets at rest
  • Binding additional authenticated data (AAD) to prevent cross-tenant reuse
A profile encrypted for tenant A cannot be decrypted in the context of tenant B, even if the raw ciphertext is copied.

​
Namespaced storage

All tenant data in GCS is stored under tenant-specific prefixes. Catalog resources, session data, and uploaded files are isolated by tenant namespace. There is no shared storage between tenants.

​
Identity boundary

Tenant membership is derived from GitHub organization membership. The platform checks org membership on every API request. A user who is not a member of the GitHub org cannot access any tenant resources — they cannot list agents, read secrets, or spawn workloads.

​
Zero secrets on disk

Your credentials are never written to any filesystem in the Murmur platform:
  1. Encryption at setup — murmur setup encrypts your credentials client-side using the tenant’s KMS key. The encrypted blob is stored in murmur.local.yaml.
  2. Transport — the encrypted profile travels through the control plane as an opaque payload. It is never decrypted during transport.
  3. Re-sealing — the control plane re-seals the profile with a per-VM ephemeral X25519 key pair using NaCl box encryption.
  4. VM decryption — the VM decrypts the profile in process memory only. The decrypted credentials are held in memory for the duration of the agent session.
  5. Destruction — when the agent session ends, the VM is destroyed. The ephemeral key pair and decrypted credentials are gone.
Developer machine          Control plane              Agent VM
┌─────────────┐          ┌──────────────┐          ┌──────────────┐
│ murmur setup│          │ control      │          │ ephemeral    │
│   ↓         │          │ worker       │          │ X25519 key   │
│ KMS encrypt │ ──blob──→│   ↓          │          │   ↓          │
│ store in    │          │ re-seal with │ ──blob──→│ NaCl decrypt │
│ local.yaml  │          │ VM pub key   │          │ in-memory    │
└─────────────┘          └──────────────┘          │ only         │
                                                    └──────────────┘

​
VM isolation

Agent VMs have no direct access to platform infrastructure:
  • No GCS access — cannot read other tenants’ data or platform internals
  • No KMS access — cannot decrypt other profiles or secrets
  • No Pub/Sub access — cannot inject events into other agents’ channels
  • No Kubernetes access — cannot reach the control plane’s internal services
All VM operations go through the murmur-api, which authenticates and authorizes every request. The VM’s short-lived service token limits what it can do to operations relevant to its own agent session.

​
Blast radius

If an agent VM is compromised, the impact is contained:
What is exposedWhat is NOT exposed
That agent’s decrypted credentials (in memory)Other agents’ credentials
That agent’s GitHub token (scoped to repos it was configured to access)Other tenants’ data
That agent’s workspace filesPlatform infrastructure
Murmur API access scoped to the agent’s permissionsKMS keys
Other developers’ profiles
Catalog secrets not assigned to that workspace
The short-lived nature of VM credentials means that even if extracted, they expire quickly. The VM itself is ephemeral — it is destroyed when the agent session ends, and cannot be reused.

​
Defense in depth

Murmur employs multiple overlapping security controls:
  1. Encryption at rest — all sensitive data is KMS-encrypted in storage
  2. Encryption in transit — TLS for all API communications, NaCl box for credential transport
  3. Ephemeral infrastructure — VMs are created per-session and destroyed after use
  4. Short-lived credentials — GitHub tokens and service tokens have limited lifetimes
  5. Least privilege — agents only have access to repos and secrets configured for their workspace
  6. Signature verification — all external events are cryptographically verified
  7. Authorization enforcement — every API call is checked against the caller’s permissions
  8. Audit trail — catalog changes are versioned with author and timestamp
For deep dives into specific security topics, see: