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.

This path is for teams comfortable with Kubernetes who want to install Cake Agents directly with Helm into an existing cluster.

​
End State

At the end of this guide you will have:
  • a cake-agents Helm release deployed to your cluster
  • a reachable control plane UI/API
  • a database connection (embedded Postgres for development or an external database)
  • session pods launching successfully in the expected namespace

​
Architecture Summary

Cake Agents has two runtime layers:
  • The control plane is a web application deployed as a standard Kubernetes workload.
  • Each user session launches a data plane pod that runs OpenCode inside the cluster.
The chart also manages supporting pieces such as RBAC, optional embedded PostgreSQL, optional Istio resources, and integration secrets.

​
Prerequisites

  • A working Kubernetes cluster
  • kubectl configured for the target cluster
  • helm 3+
  • A registry path and image tags for the Cake Agents images
  • A DNS name for the control plane if exposing it externally
  • Kubernetes secrets or secret-management flow for integration credentials
If you plan to use the chart exactly like the repo’s dev flow, the cluster also needs access to the ECR registry that serves the images.

​
What the Helm Chart Configures

The Helm install configures these main concerns:
  • Control plane deployment, service account, probes, and service
  • Session namespace selection through sessionNamespace.name
  • RBAC for creating and managing session workloads
  • Embedded PostgreSQL for development, or an external database via externalDatabase.existingSecret
  • Optional External Secrets generation for PostgreSQL credentials
  • Secret wiring for integrations and auth
  • Optional Istio gateway and routing resources

​
Choose a Database Strategy

For development, the chart defaults to embedded PostgreSQL. For shared or production-like environments, use an external database and provide a secret instead: 
externalDatabase:
  existingSecret: cake-agents-db
  existingSecretKey: DATABASE_URL

postgresql:
  enabled: false
The chart also supports mapping individual database env vars from a secret with externalDatabase.existingSecretEnv.

​
Create Required Secrets

At minimum, decide how you will supply integration and auth material for the release. In Cake Agents, sensitive values generally live in one of two places:
  • Kubernetes secrets, when the control plane or session runtime needs a secret mounted or injected at runtime
  • The database, when the system stores linked account credentials, auth state, provider configuration, or brokered tokens on behalf of the user
Common Kubernetes-managed inputs include database connection material and environment-scoped integration credentials. User-linked credentials and session-linked auth state are generally persisted in the application database. If you are supplying integration secrets in Kubernetes, the common categories are (exact keys can vary by chart version):
  • linear.secret
  • litellm.secret
  • slack.secret
  • betterAuth.secret
You can let the chart create secret objects, or point it at existing ones. Example: 
linear:
  secret:
    create: false
    name: linear

litellm:
  secret:
    create: false
    name: litellm

slack:
  secret:
    create: false
    name: slack
If you are integrating with an external secret manager, keep create: false and provision those secrets ahead of the Helm install. For Slack credentials specifically, see Configure Slack credentials.

​
Header Auth

Header auth lets Cake Agents trust a fronting authentication proxy for user identity instead of handling the primary login challenge itself. When headerAuth.enabled=true, Cake Agents trusts an upstream proxy or gateway to authenticate the user and forward identity headers to the control plane. In this model:
  • your ingress layer performs the real user authentication
  • Cake Agents reads trusted identity headers from the request
  • the control plane maps those headers into the application user context
This is a good fit when Cake Agents sits behind a standard authenticating proxy such as oauth2-proxy, an API gateway, or another trusted SSO layer. Typical headers include email, user display name, and an access token or JWT header. A minimal example: 
headerAuth:
  enabled: true
  email:
    header: x-auth-request-email
  jwt:
    header: x-auth-request-access-token
  user:
    header: x-auth-request-user
Use header auth only when the control plane is reachable exclusively through a trusted reverse proxy, API gateway, or auth proxy that strips spoofed headers from incoming traffic. If you do not have that boundary, prefer the application’s native auth and SSO configuration instead of trusting request headers directly. For a detailed configuration reference, see Header authentication.

​
Choose How Sessions Are Namespaced

Session workloads run in sessionNamespace.name, which defaults to the Helm release namespace. If you want session pods in a separate namespace: 
sessionNamespace:
  name: cake-agents-sessions
  create: true
The chart installs RBAC for session workload management in that namespace. This matters because the control plane uses the Kubernetes API during session lifecycle operations.

​
Minimal Values File

Start from a small values file and expand from there: 
registry:
  default: <registry>

controlPlane:
  host: agents.example.com
  image:
    repository: cake-agents/web
    tag: <image-tag>

dataPlane:
  image:
    repository: cake-agents/data-plane
    tag: <image-tag>

dataPlaneInit:
  image:
    repository: cake-agents/data-plane-init
    tag: <image-tag>

externalDatabase:
  existingSecret: cake-agents-db
  existingSecretKey: DATABASE_URL

postgresql:
  enabled: false

headerAuth:
  enabled: true
  email:
    header: x-auth-request-email
  jwt:
    header: x-auth-request-access-token
  user:
    header: x-auth-request-user
Those header auth values are useful when Cake Agents sits behind an authenticating proxy.

​
Install with Helm

helm dependency build charts/cake-agents
helm upgrade --install cake-agents charts/cake-agents \
  --namespace cake-agents \
  --create-namespace \
  -f /path/to/values.yaml \
  --wait --timeout 5m
Most teams should keep an environment-specific values file that captures their database wiring, ingress model, auth strategy, and secret references.

​
Verify the Deployment

Check the release and workloads: 
helm status cake-agents -n cake-agents
kubectl get pods -n cake-agents
kubectl get secret -n cake-agents
Then confirm:
  • the control plane pod is healthy
  • the configured host resolves to the ingress or gateway
  • the app can reach the database
  • creating a session produces a data plane pod in the expected namespace

​
Istio and Ingress Notes

The chart supports Istio resources behind istio.enabled. If you already have a shared gateway, set istio.gateway.name to that gateway rather than creating a new one. If you are not using Istio, keep it disabled and expose the control plane with your cluster’s standard ingress pattern.

​
Operational Notes

  • Embedded PostgreSQL is intended for development.
  • Session pods run OpenCode on port 4096 inside each pod.
  • The control plane needs RBAC to manage session workloads.
  • If a release is left in pending-install or pending-upgrade, recover it with normal Helm troubleshooting and rollback practices.
For the platform model behind these resources, see Core Concepts.