Getting Started with Kubernetes

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 DNS name for the control plane
An ingress controller or API gateway configured to route traffic to the control plane (e.g. Istio, Nginx, ALB, etc.)
Kubernetes secrets or secret-management flow for integration credentials
Optionally, a preexisting Postgres database

What the Helm Chart Configures

The Helm install configures these main concerns:

Control plane deployment, service account, probes, and service
RBAC for creating and managing session workloads
Embedded PostgreSQL for development, or an external database via externalDatabase.existingSecret
Secret wiring for integrations and auth

Set up DNS

Cake Agent’s control plane needs to be reachable at a stable DNS name. This is used for user linking flows and should match the controlPlane.host value in the Helm chart.

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

If manually provisioning this secret, you may want to first create the namespace.

kubectl create namespace cake-agents

Then apply a secret manifest that looks like this:

apiVersion: v1
kind: Secret
metadata:
  name: cake-agents-db
  namespace: cake-agents
type: Opaque
stringData:
  DATABASE_URL: postgres://username:password@hostname:port/database

Set up an auth client

Cake Agents uses OIDC for authentication. You can use any compliant provider, or delegate auth to an authenticating proxy via trusted headers. In your OIDC provider, create a new client with these settings:

Client type: Confidential or Public (with PKCE)
Redirect URI: https://<controlPlane.host>/api/auth/callback/oidc
Scopes: openid email profile

Export the client ID and secret for the next step. If using a public client, you can omit the secret.

kind: Secret
apiVersion: v1
metadata:
  name: sso-oidc
  namespace: cake-agents
type: Opaque
stringData:
  clientSecret: <your-client-secret>

Minimal Values File

Start from a small values file and expand from there:

image:
  tag: 0.5.0

controlPlane:
  host: agents.example.com
  extraHosts:
  - auth.example.com

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

oidc:
  enabled: true

  providerId: oidc
  domain: example.com
  issuer: https://auth.example.com
  clientId: <your-oidc-client-id>
  clientSecret:
    create: false
    # Should match your provisioned secret
    name: sso-oidc
    key: clientSecret

postgresql:
  enabled: false

Install with Helm

If manually installing, you’ll need to first assume an identity in your AWS account that has permissions to pull the control plane. Then, you can log into ECR and use that to authenticate helm to Cake’s private registry. For example:

aws ecr get-login-password --region us-east-2 | helm registry login --username AWS --password-stdin 684117700585.dkr.ecr.us-east-2.amazonaws.com

Then you can install the chart with your values file:

helm upgrade --install cake-agents \
  oci://684117700585.dkr.ecr.us-east-2.amazonaws.com/charts/cake-agents \
  --version 0.5.0 \
  --namespace cake-agents \
  --create-namespace \
  -f /path/to/values.yaml \
  --wait --timeout 5m

Once you’re installed, you’ll need to configure your ingress or gateway to route traffic to the control plane service. If using Istio, you can enable the built-in gateway configuration in the chart and point your DNS at the gateway’s external IP. After you can reach the control plane in the browser, you’re ready to set up integrations:

Optional: S3 object storage

The control plane can optionally use an S3-compatible bucket for object storage. This is disabled by default; enable it when a feature you use requires durable object storage. Set the s3.* values to bootstrap the connection:

s3:
  enabled: true
  bucket: cake-agents-prod
  region: us-east-2
  # Optional: override for S3-compatible providers (e.g. MinIO, R2)
  endpoint: ""
  # Optional: key prefix applied to all objects
  prefix: ""

Credentials are resolved by the AWS SDK’s default provider chain, so use whichever flow fits your cluster:

An IAM role attached to the control plane service account (IRSA on EKS, Workload Identity on GKE)
Standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars supplied via controlPlane.deployment.extraEnv

If s3.region or s3.endpoint are unset, the control plane also accepts the standard AWS_REGION and AWS_ENDPOINT_URL_S3 env vars.

Optional: Session pod resources

Each session runs in its own data plane pod. By default, the control plane requests 640Mi of memory for every new session container so the Kubernetes scheduler places sessions on nodes with enough headroom. Set dataPlane.resources to change this. The value accepts a full Kubernetes resource requirements block, so you can set both requests and limits:

dataPlane:
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      memory: 2Gi

Changes apply to sessions created after the Helm upgrade. Existing session pods keep the resources they were created with.

Optional: Custom sign-out URL

By default, when a user selects sign out in the web UI, Cake Agents ends the user’s session and returns them to the Cake Agents sign-in page. If you delegate auth to an authenticating proxy such as oauth2-proxy with headerAuth, the proxy’s own session stays active. The user is signed straight back in on the next request. Set controlPlane.signOutUrl to send users to your proxy’s sign-out endpoint instead:

controlPlane:
  signOutUrl: /oauth2/sign_out?rd=/

When a user signs out, Cake Agents ends its own session first and then redirects the browser to this URL. The redirect happens even if ending the Cake Agents session fails.

Relative paths are resolved against the public origin of the control plane. A full URL also works.
For oauth2-proxy, include the rd query parameter to set where the proxy sends the user after sign-out. Without rd, the browser loops on /oauth2/sign_out.
If you serve Cake Agents under a pathPrefix, point rd at that path, for example /oauth2/sign_out?rd=/cake-agents/.

Leave signOutUrl empty to keep the default behavior.

Values Reference

registry:
  # Shared fallback registry used when controlPlane/dataPlane/dataPlaneInit image registry is empty.
  default: 684117700585.dkr.ecr.us-east-2.amazonaws.com

# Global image defaults.
image:
  # Used when a component-specific image.tag is unset/empty.
  tag: latest

controlPlane:
  # Note: control plane is not yet designed for multi-replica operation
  # and should be deployed with replicaCount: 1 for now.
  replicaCount: 1
  image:
    registry: ""
    repository: cake-agents/web
    tag: latest
    pullPolicy: Always
  imagePullSecrets: []
  # Public host used by Istio ingress resources and default ALLOWED_HOSTS.
  host: ""
  # Additional entries appended to ALLOWED_HOSTS (Vite-style: leading `.` = suffix).
  extraHosts: []
  # Web UI sign-out redirect (e.g. oauth2-proxy: /oauth2/sign_out?rd=/).
  # Resolved against the public origin. Empty keeps the default sign-out behavior.
  signOutUrl: ""
  deployment:
    # Set to override data plane image entirely (e.g. CI tag)
    dataPlaneImage: ""
    # Set to override data plane init image entirely (e.g. CI tag)
    dataPlaneInitImage: ""
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
    livenessProbe:
      path: /api/health
      periodSeconds: 30
      failureThreshold: 3
    readinessProbe:
      path: /api/health
      periodSeconds: 10
      failureThreshold: 3
    startupProbe:
      path: /api/health
      periodSeconds: 10
      failureThreshold: 30
    extraEnv: []
  serviceAccount:
    create: true
    automount: true
    annotations: {}
    name: ""
  podAnnotations: {}
  podLabels: {}
  nodeSelector: {}
  tolerations: []
  affinity: {}

nameOverride: ""
fullnameOverride: ""

# Base path for the control plane.
pathPrefix: /

# K8s namespace for session data plane workloads.
sessionNamespace:
  # Namespace to use for session workloads (empty = release namespace).
  name: ""
  # Create `sessionNamespace.name` when it differs from the release namespace.
  create: false

# Existing secret containing a full DATABASE_URL. If unset, this chart uses
# the embedded Bitnami PostgreSQL secret + env var composition in the web pod.
externalDatabase:
  existingSecret: ""
  existingSecretKey: DATABASE_URL
  # Optional map of secret key -> env var name (e.g. PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD).
  # When set, these env vars are injected from existingSecret and existingSecretKey is ignored.
  existingSecretEnv: {}

# Embedded PostgreSQL (recommended for development only).
# For production, prefer an externally managed database and set externalDatabase.existingSecret.
postgresql:
  enabled: true
  auth:
    username: postgres
    # Leave empty to let the subchart generate and persist a random admin password.
    password: ""
    # Optional existing secret used by the Bitnami subchart for auth credentials.
    # Must contain key `postgres-password` (and usually `password`).
    existingSecret: ""
    database: postgres
  primary:
    persistence:
      enabled: true
      size: 1Gi

# Optional External Secrets integrations.
externalSecrets:
  # Generate embedded PostgreSQL credentials using ESO and write them to
  # `postgresql.auth.existingSecret`.
  enabled: false
  # Recommended for previews: create once and do not rotate while PVC exists.
  refreshPolicy: CreatedOnce
  refreshInterval: 0s
  generator:
    length: 32
    digits: 8
    symbols: 8
    noUpper: false
    allowRepeat: true

sessionVolume:
  # EBS volumes cannot be smaller than 1 GiB.
  initialSize: 1Gi
  # Empty = use cluster default StorageClass
  storageClassName: ""

# Automatic session volume expansion. See the session volume autoscaling page.
diskAutoscale:
  # Requires EKS kubelet fine-grained authorization.
  enabled: true
  cronExpression: "* * * * *"
  highWatermarkRatio: 0.9
  scaleFactor: 1.5
  minIncrement: 1Gi
  maxVolumeSize: 128Gi

rbac:
  # Permissions for session workload management in sessionNamespace.
  enabled: true

# Data plane configuration
dataPlane:
  # Resources assigned to each newly created session's data-plane container.
  resources:
    requests:
      memory: 640Mi
  image:
    registry: ""
    repository: cake-agents/data-plane
    tag: main

dataPlaneInit:
  image:
    registry: ""
    repository: cake-agents/data-plane-init
    tag: main

# Cake Agents uses Better Auth for user account management and auth.
# The chart by default creates a random secret used for signing session
# cookies. You can also provide your own secret or integrate with an
# external secret manager.
betterAuth:
  secret:
    # When externalSecrets.enabled=true, the chart renders an ExternalSecret that
    # generates this Secret once (refreshPolicy defaults to CreatedOnce).
    # When externalSecrets.enabled=false, the chart creates a v1 Secret with a
    # generated value (stable across Helm upgrades via lookup).
    create: true
    # Secret name in the release namespace.
    name: better-auth
    # Annotations applied to the Secret (or ExternalSecret target Secret) when create=true.
    annotations: {}
    # Map of logical keys -> Secret data keys.
    keys:
      # Secret data key used for BETTER_AUTH_SECRET.
      secret: secret

# Session authentication uses a dedicated HMAC key for data-plane credentials.
# This Secret is mounted only into the control-plane deployment.
sessionAuth:
  secret:
    # When externalSecrets.enabled=true, the chart renders an ExternalSecret that
    # generates this Secret once (refreshPolicy defaults to CreatedOnce).
    # When externalSecrets.enabled=false, the chart creates a v1 Secret with a
    # generated value (stable across Helm upgrades via lookup).
    create: true
    # Secret name in the release namespace.
    name: session-auth
    # Annotations applied to the Secret (or ExternalSecret target Secret) when create=true.
    annotations: {}
    # Map of logical keys -> Secret data keys.
    keys:
      # Secret data key used for SESSION_AUTH_HMAC_KEY.
      hmacKey: hmacKey

# Cake Agents supports OIDC authentication with any compliant provider. When
# enabled, users are redirected to the OIDC provider for login.
#
# Required OIDC scopes include: openid email profile.
oidc:
  enabled: false
  # Cake Agents internal provider ID. In the future, Cake may support
  # multiple providers and this ID will be used to distinguish them
  providerId: ""
  # Restricts login to users with an email address in the specified
  # domain (e.g. `example.com`).
  domain: ""
  # Issuer URL for OIDC discovery. Must support the well-known OIDC config endpoint.
  issuer: ""
  # Client ID from the OIDC provider. Required for both confidential and public clients.
  clientId: ""
  # For public OIDC clients (PKCE), set to true and omit client secret.
  publicClient: false
  pkce: true
  # Client secret from the OIDC provider. Required for confidential clients, must be omitted for public clients.
  clientSecret:
    # Create an empty Secret scaffold in the release namespace.
    # Set to false to reference an existing Secret.
    create: false
    name: sso-oidc
    annotations: {}
    key: clientSecret

# Alternatively, Cake supports delegating auth to an authenticating proxy
# via trusted header. When headerAuth.enabled=true, Cake Agents reads user
# identity from an OIDC ID Token (jwt.header) or directly from headers
# (email.header, user.header) set by the proxy. If using OIDC, the user's
# full name and email address must be present in the token claimed.
# Recommended OIDC scopes: openid email profile
headerAuth:
  enabled: false
  email:
    header: ""
    claim: email
  jwt:
    header: ""
  user:
    header: ""
    claim: name

# Optional S3 object storage bootstrap. Disabled by default.
# Credentials use the AWS SDK default provider chain (IRSA, env vars, etc.).
s3:
  enabled: false
  # Target bucket name.
  bucket: ""
  # AWS region. Falls back to AWS_REGION when unset.
  region: ""
  # Optional custom endpoint for S3-compatible providers (MinIO, R2, etc.).
  # Falls back to AWS_ENDPOINT_URL_S3 when unset.
  endpoint: ""
  # Optional key prefix applied to all objects.
  prefix: ""

# If using Istio, the chart can optionally configure an Istio Gateway and VirtualService to route traffic to the control plane. You can also export the gateway credential for use in external DNS and TLS configuration.
istio:
  enabled: false
  inject: true
  gateway:
    # Use a shared cluster gateway (namespace/name) or leave empty and set create: true for a chart-owned Gateway.
    name: ""
    create: false
    credentialName: istio-gateway-certificate-tls
  authorizationPolicy:
    # Create ingressgateway ALLOW and oauth2-proxy CUSTOM AuthorizationPolicies
    # for the control plane host/path. Enabled by default so the chart manages
    # ingress auth even when it doesn't own the Istio Gateway.
    create: true

Ingress authorization policies

When istio.enabled is true, the chart always creates in-namespace AuthorizationPolicy resources that restrict traffic to the control plane pods (allowing the Istio ingress gateway and same-namespace callers). By default, istio.authorizationPolicy.create is true, so the chart also creates the ingress-side policies in the istio-system namespace: an ALLOW policy that scopes traffic to your controlPlane.host and pathPrefix, and a CUSTOM policy that routes authenticated paths through oauth2-proxy while leaving webhook endpoints (Linear, Slack, setup finalize) open. Set istio.authorizationPolicy.create to false if another controller in your cluster already provisions these policies for the control plane host, or if you manage ingress-side authorization outside the chart.

Overview

Getting Started

Administration

Users

Getting Started with Kubernetes

End State

Architecture Summary

Prerequisites

What the Helm Chart Configures

Set up DNS

Choose a Database Strategy

Set up an auth client

Minimal Values File

Install with Helm

Optional: S3 object storage

Optional: Session pod resources

Optional: Custom sign-out URL

Values Reference

Ingress authorization policies

​End State

​Architecture Summary

​Prerequisites

​What the Helm Chart Configures

​Set up DNS

​Choose a Database Strategy

​Set up an auth client

​Minimal Values File

​Install with Helm

​Optional: S3 object storage

​Optional: Session pod resources

​Optional: Custom sign-out URL

​Values Reference

​Ingress authorization policies

End State

Architecture Summary

Prerequisites

What the Helm Chart Configures

Set up DNS

Choose a Database Strategy

Set up an auth client

Minimal Values File

Install with Helm

Optional: S3 object storage

Optional: Session pod resources

Optional: Custom sign-out URL

Values Reference

Ingress authorization policies