Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cake.ai/llms.txt

Use this file to discover all available pages before exploring further.

Cake Agents separates long-lived platform services from per-session execution.

​
Control Plane

The control plane is the main web application deployed by the Cake Agents Helm chart. It is responsible for:
  • serving the UI and API
  • authenticating users
  • storing durable application state in PostgreSQL
  • creating and tracking session workloads in Kubernetes
  • proxying or coordinating access to the per-session OpenCode runtime
It is the system of record for users, session metadata, visibility, linked accounts, provider configuration, and the logic that decides what a given user is allowed to do.

​
Data Plane

Each session launches a dedicated data plane pod. That pod runs OpenCode and any session-scoped resources needed for interactive work. This keeps session execution isolated from the control plane and from other users’ sessions. The control plane is long-lived and stateful at the application level. Data plane pods are session-scoped execution environments.

​
Session Lifecycle

Each Cake session gets its own OpenCode instance. The lifecycle is:
  1. A user creates a Cake session in the control plane.
  2. Cake provisions the Kubernetes resources for that session.
  3. The session data plane starts and runs an OpenCode instance.
  4. The control plane connects to that OpenCode instance and streams messages, events, and status back to the user.
  5. When the session is deleted, Cake tears down the session resources.
Key mental model: a Cake session is the user-facing unit of work, and each one has a dedicated OpenCode runtime behind it.

​
Session Namespace

Session pods run in the release namespace by default, or in a separate namespace if sessionNamespace.name is set. The control plane needs RBAC for that namespace because session lifecycle operations call the Kubernetes API directly.

​
Permission Model

Cake Agents permission modeling starts from ownership and visibility.
  • Every Cake session has an owner.
  • Private sessions are visible only to their owner.
  • Public sessions can be listed and observed by other users.
  • Destructive actions such as deleting a session remain owner-scoped.
This is an application-layer permission model enforced by the control plane before it proxies actions to the data plane. There is also a separate infrastructure permission layer:
  • Kubernetes RBAC controls what the control plane service account can do in the cluster.
  • Cloud IAM controls what infrastructure automation and supporting services can do outside the cluster.
Application permissions decide who may act on a session. Infrastructure permissions decide what the platform is technically allowed to provision or access.

​
Database Model

Cake Agents can run with:
  • embedded PostgreSQL from the Helm chart for development
  • an external PostgreSQL database for shared or production-style environments
A Terraform-based deployment commonly provisions an external database and passes connection credentials into Kubernetes as a secret.

​
Secrets and Credential Brokering

These credentials do not all live in the same place.
  • Environment-scoped operational secrets often live in Kubernetes secrets.
  • User-linked credentials, refresh tokens, auth accounts, provider configuration, and some internal session auth material are stored in the application database.
Credential brokering is the process of taking a user or environment credential held by the control plane and making only the needed access available to a session runtime. In practice, that means:
  • the control plane owns the durable auth relationship
  • the control plane decides whether the current user is allowed to use a credential in a given session
  • the data plane receives only the scoped access it needs for runtime actions
This is especially important for user-linked integrations such as GitHub access. The goal is to avoid treating long-lived user credentials as cluster-global secrets.

​
Header Auth

Header auth is an integration pattern where identity is asserted by a trusted upstream proxy instead of by an interactive login flow handled entirely inside Cake Agents. When enabled:
  • an upstream component authenticates the user
  • Cake Agents trusts specific headers for user identity
  • the control plane turns those headers into application user context and permissions
This can work well in environments with a standard auth gateway, but it is only safe when the network boundary guarantees that untrusted clients cannot inject those headers directly.

​
Infrastructure Layers

Across the platform, responsibilities break down like this:
  • application runtime and Helm packaging
  • cloud infrastructure, EKS platform resources, and environment wiring

​
Architecture Diagram

Users connect to the control plane, the control plane stores state in PostgreSQL, and each session runs in its own data plane pod that hosts OpenCode. Diagram reference:
  • Session workloads are launched by the application into Kubernetes.
  • A Terraform-based environment can provision the cluster, database, and Helm release that host the control plane.

​
Choosing a Deployment Path

  • Use the Kubernetes path if you already have a cluster and platform primitives in place.
  • Use the Terraform path if you want Cake Agents deployed as part of a fuller AWS environment definition.