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, including a per-session service account
A ClusterRole that lets the control plane read the cluster’s service account signing keys, used to authenticate session pods
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
Redirect URI: https://<controlPlane.host>/api/auth/callback/oidc
Scopes: openid email profile

Export the client ID and secret for the next step. Cake Agents requires a client secret. Public clients that rely only on PKCE (Proof Key for Code Exchange) aren’t supported.

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:

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

Cake publishes release versions of the chart to a public registry at oci://public.ecr.aws/kflow/charts/cake-agents. You don’t need to authenticate to pull the chart. To inspect a release before you install it, run:

helm show chart oci://public.ecr.aws/kflow/charts/cake-agents --version 0.5.0

Install the chart with your values file:

helm upgrade --install cake-agents \
  oci://public.ecr.aws/kflow/charts/cake-agents \
  --version 0.5.0 \
  --namespace cake-agents \
  --create-namespace \
  -f /path/to/values.yaml \
  --wait --timeout 5m

Each released chart version sets image.tag to the matching release image tag by default. For example, chart 0.5.0 deploys the 0.5.0 images. You don’t need to set image.tag in your values file. Set image.tag or a component-specific tag such as controlPlane.image.tag only when you need to run different images than the chart release. Only the chart is public. By default, the chart pulls container images from Cake’s private registry at 684117700585.dkr.ecr.us-east-2.amazonaws.com. Your cluster nodes need permission to pull from that registry. Alternatively, mirror the images and override registry.default or the component-specific image registries, such as controlPlane.image.registry, in your values file. 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:

Session pod authentication

Session pods authenticate to the control plane with per-session service account tokens. See Data plane authentication for how this works. With rbac.enabled: true, the chart grants everything this needs. If you set rbac.enabled: false and manage RBAC yourself, grant the control plane service account:

create, get, list, watch, update, patch, and delete on serviceaccounts in the session namespace
get on the non-resource URLs /.well-known/openid-configuration and /openid/v1/jwks

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cake-agents-oidc-discovery
rules:
- nonResourceURLs:
  - /.well-known/openid-configuration
  - /openid/v1/jwks
  verbs:
  - get

The control plane loads signing keys from the jwks_uri your kube-apiserver advertises. On some clusters, such as EKS, this is a public HTTPS endpoint outside the cluster. Make sure egress rules let the control plane reach it. When you upgrade from a version without per-session service accounts, the control plane migrates running sessions at startup. It creates each session’s service account and updates the session’s StatefulSet, which restarts the pod. The session’s workspace volume and OpenCode state persist across the restart.

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 sets these resources on every session container:

A 1Gi memory request and a 250m CPU request, so the Kubernetes scheduler places sessions on nodes with enough headroom.
A 16Gi memory cap and a 3 CPU limit, so one runaway session can’t consume an entire node. Each session starts with a memory limit equal to its memory request. The agent can raise the limit up to the cap and lower it back down to the request. See Automatic memory resizing.
A 1Gi ephemeral storage request and a 10Gi ephemeral storage limit, which cap how much node-local disk a session can use.

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: 2Gi
    limits:
      cpu: "4"
      memory: 12Gi

In this example, each session starts with a 2Gi memory limit. The agent can raise it to 12Gi. Memory and CPU changes apply to sessions created after the Helm upgrade. Existing session pods keep the memory and CPU they were created with.

Session memory and CPU limits

If a session uses more memory than its current memory limit, Kubernetes stops and restarts the session container. This is called an OOM kill (out of memory). The pod, session volume, and files in /workspace are kept. If the agent was mid-turn, it resumes automatically after the restart. If a session reaches limits.cpu, Kubernetes slows it down instead of stopping it. If heavy builds feel slow, raise or remove limits.cpu first. Always set a memory and CPU request alongside each limit. If you set only a limit, Kubernetes uses the limit as the request. The scheduler then reserves the full limit for every session, which reduces how many sessions fit on each node. The CPU request reserves capacity on each node. Raising requests.cpu or requests.memory lowers the number of sessions that fit on a node.

Automatic memory resizing

The agent can change its own session’s memory limit. It raises the limit when a command runs out of memory. It lowers the limit to give memory back to the cluster, for example after a memory-heavy job finishes. The agent uses two tools from the Cake MCP server:

session_memory_status reports the current memory limit, the cap, and whether a resize is in progress. It doesn’t change anything.
memory_limit sets the memory limit to a target size. The agent must pass targetMemoryGib, a whole number of GiB from 1 to 64. The control plane compares the target with the current limit and raises or lowers it to match.

The control plane clamps the target to stay within these bounds:

Raises stop at the memory cap.
Lowers stop at the session’s memory request (dataPlane.resources.requests.memory). A limit can’t go below its request.

The control plane resizes the running pod in place, so the agent’s process keeps running. With rbac.enabled: false, also grant the control plane service account patch on pods/resize in the session namespace.

Raise the memory limit

A raised limit applies within seconds. In-place resize requires Kubernetes 1.33 or later. If the cluster doesn’t support it, or the node can’t fit the larger limit, the control plane replaces the pod with the new limit instead. The new pod may run on a different node. The session restarts briefly, and its volume and files are kept. A raised limit doesn’t always survive a pod restart. The control plane writes it into the session’s pod spec only when the pod is already being replaced. Until then, a replaced pod comes back at the previous limit, and the agent can request more memory again.

Lower the memory limit

Lowering a memory limit in place requires Kubernetes 1.35 or later. A lower limit applies once the session’s current memory usage is below it. Until then, the kubelet holds the resize as pending and keeps retrying. The tool reports this as a pending resize, not an error. After a lower, commands that need more memory than the new limit are OOM killed. The agent can raise the limit again with the same tool. Kubernetes rejects a lower limit in these cases:

The cluster runs Kubernetes 1.34 or earlier.
Session pods use the Guaranteed QoS class, meaning every CPU and memory request equals its limit. The default session resources use different CPU request and limit values, so session pods are Burstable.

A lowered limit isn’t written into the session’s pod spec. If the pod is replaced, it comes back at the limit stored in its pod spec, and the agent can lower it again.

Set the memory cap

The memory cap is the largest memory limit a session can grow to. By default, the cap is dataPlane.resources.limits.memory from your Helm values. Raising the cap doesn’t change what the scheduler reserves for each session. The scheduler only reserves requests.memory. Organization admins can override the cap without a Helm upgrade:

Go to Settings → Organization → Sessions.
In Max Memory, enter a whole number and select Mi or Gi.
Select Save.

To return to the Helm value, clear the field and select Save, or select Reset to Default. The control plane reads the cap each time the agent requests more memory. A new cap applies to running sessions immediately and doesn’t restart any pods. Lowering the cap never reduces a session’s current memory limit. It only stops further increases above the new cap. The Max Memory setting replaces the Helm cap entirely, so it can be higher or lower than dataPlane.resources.limits.memory. If you raise it, make sure your nodes have enough memory for the larger limits.

Session disk limit

Ephemeral storage is node-local disk that a session uses outside its persistent session volume. It covers /tmp, tools installed into system directories, and container logs. Files in /workspace and the home directory (/root) live on the session volume and don’t count toward the limit. Package manager caches such as ~/.npm and ~/.cache are in the home directory, so they use the session volume’s space instead of node disk. Heavy caches can fill the session volume. Enable session volume autoscaling to grow it automatically. If a session goes over limits.ephemeral-storage, Kubernetes evicts that session pod. This stops one runaway session from filling the node’s disk and affecting other sessions. Kubernetes checks disk usage periodically, so a session that writes very quickly can briefly exceed the limit before eviction. To change the limit, override the ephemeral-storage entries:

dataPlane:
  resources:
    requests:
      memory: 1Gi
      cpu: 250m
      ephemeral-storage: 2Gi
    limits:
      memory: 16Gi
      cpu: "3"
      ephemeral-storage: 20Gi

Always set requests.ephemeral-storage together with the limit, and keep the request well below it. If you set only a limit, Kubernetes uses the limit as the request. The scheduler then reserves the full limit for every session, which reduces how many sessions fit on each node. The control plane applies ephemeral storage changes to running sessions when it starts.

Upgrading to a release that adds or changes the disk limit restarts every running session pod once. Files in /workspace, session history, and attachments are kept. Agent work in progress when the pod restarts is interrupted, then resumes automatically.

Upgrading to a release that moves the home directory onto the session volume also restarts every running session pod once. Files in /workspace, session history, and attachments are kept. Files the agent previously wrote to /root aren’t carried over.

Interrupted agent turns

A session container can restart while the agent is working. This happens after an OOM kill, an eviction, or an upgrade that restarts session pods. When the container starts again, Cake Agents checks whether the session’s last agent turn finished. If it didn’t, Cake Agents sends the agent a hidden continue prompt so it picks up where it stopped. You don’t need to configure anything. Cake Agents doesn’t resume a turn in these cases:

The turn finished before the restart, or a user stopped it.
Someone sent a new message after the interrupted turn.
The session already resumed 3 times in a row without completing a turn. This stops a session that crashes repeatedly from restarting the same work in a loop. The count resets after a turn completes.

Optional: Session pod scheduling

By default, Kubernetes can schedule session pods on any node in the cluster. Use dataPlane.nodeSelector and dataPlane.tolerations to run sessions on a dedicated group of nodes. For example, you can keep sessions apart from other workloads or give them their own Karpenter node pool.

dataPlane.nodeSelector is a map of node labels. Kubernetes places session pods only on nodes that have every listed label.
dataPlane.tolerations lists tolerations that let session pods run on tainted nodes. Each entry takes a required key and optional operator, value, and effect.

To reserve nodes for sessions, taint them so other pods stay off, then add a matching toleration and node selector:

dataPlane:
  nodeSelector:
    karpenter.sh/nodepool: cake-agents-sessions
  tolerations:
    - key: dedicated
      value: cake.ai/sessions
      effect: NoSchedule

A toleration only allows session pods onto tainted nodes. It doesn’t keep them off other nodes. Set a node selector too if sessions must run only on the dedicated nodes.

Value	Default	Description
`dataPlane.nodeSelector`	`{}`	Node labels that session pods must match.
`dataPlane.tolerations`	`[]`	Tolerations added to session pods so they can run on tainted nodes.

These values apply only to session pods. To schedule the control plane, use controlPlane.nodeSelector and controlPlane.tolerations.

Setting or changing these values restarts every running session pod once, after the control plane picks up the new configuration. Files in /workspace, session history, and attachments are kept. Agent work in progress is interrupted, then resumes automatically.

Optional: Kubernetes API access from sessions

By default, session pods can’t call the Kubernetes API. Turn this on when you want session agents to inspect the cluster they run in. For example, an agent can read pod logs while debugging a Cake Agents deployment. Access has two parts:

dataPlane.automountServiceAccountToken mounts a standard Kubernetes token in each session pod. Tools like kubectl find it at the default path, /var/run/secrets/kubernetes.io/serviceaccount.
dataPlane.roles lists existing Roles or ClusterRoles that grant permissions to that token. On its own, the token can’t do anything.

dataPlane:
  automountServiceAccountToken: true
  roles:
    - kind: Role
      name: cake-agents-dataplane-pod-debug
      # namespace: other-namespace  # omit to bind in the session namespace

For each session, the control plane creates one RoleBinding per entry and binds it to that session’s service account. A RoleBinding grants access only in its own namespace. Set namespace to grant access outside the session namespace. Ending a session deletes its RoleBindings. When the control plane starts, it also adds newly listed roles to running sessions, without restarting them.

Value	Default	Description
`dataPlane.automountServiceAccountToken`	`false`	Mounts a cluster token in session pods so in-session tools can reach the Kubernetes API.
`dataPlane.roles`	`[]`	Roles to bind to every session. Each entry takes `kind` (`Role` or `ClusterRole`), `name`, and an optional `namespace`.

With an empty roles list, the control plane makes no RoleBinding API calls. Session authentication to the control plane works the same way whether or not you enable this feature.

Grant the control plane permission to bind roles

The chart doesn’t create the listed roles. It also doesn’t give the control plane permission to bind them. Before you list a role:

Create the Role or ClusterRole in the cluster, outside the Cake Agents release.
Give the control plane service account create, get, list, and delete on rolebindings in every target namespace.
Give the control plane bind on each listed role, limited with resourceNames.

Kubernetes lets a caller create a RoleBinding only when the caller already holds every permission in the role, or holds bind on it. A bind grant limited by resourceNames restricts the control plane to exactly the roles you list:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: cake-agents-session-role-binder
  namespace: cake-agents  # session namespace
rules:
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["rolebindings"]
    verbs: ["create", "get", "list", "delete"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["roles"]
    verbs: ["bind"]
    resourceNames: ["cake-agents-dataplane-pod-debug"]

Bind this Role to the control plane service account with a RoleBinding. If the control plane can’t create a RoleBinding, for example because of a 403 Forbidden response, session creation fails. The control plane validates dataPlane.roles at startup and refuses to start when an entry is malformed or two entries resolve to the same role and namespace.

Every listed role applies to every session. Any user who can create a session gets its permissions. The chart’s session workloads Role already grants the control plane pods, pods/exec, and secrets in the session namespace. That means the control plane can bind a role within those permissions without any extra grant. Review every role before you list it.

Under a bind grant, Kubernetes doesn’t check that the referenced role exists. A misspelled role name creates a RoleBinding that grants nothing, without an error. Check that each role exists in its target namespace. The control plane logs every RoleBinding it creates with its role reference.

Upgrading to a release that adds this feature restarts every running session pod once, even if you leave it disabled. Files in /workspace, session history, and attachments are kept.

Optional: Additional volumes in session pods

Use dataPlane.additionalVolumes and dataPlane.additionalVolumeMounts to mount extra Kubernetes volumes into every session pod. A common use is giving session agents credentials for an external service. For example, you can mount an EKS IAM roles for service accounts (IRSA) token so in-session tools can assume an AWS role.

dataPlane.additionalVolumes takes a list of standard Kubernetes volumes. Any volume type works, such as projected, configMap, or secret. Each entry needs a name.
dataPlane.additionalVolumeMounts takes a list of standard Kubernetes volume mounts. Each entry needs a name that matches a declared volume and an absolute mountPath. readOnly and the other volume mount fields are optional.

The chart passes both lists through to the session pod spec unchanged. Cake Agents adds them after its built-in volumes and mounts. This example mounts an IRSA token and a ConfigMap:

dataPlane:
  additionalVolumes:
    - name: aws-iam-token
      projected:
        sources:
          - serviceAccountToken:
              audience: sts.amazonaws.com
              expirationSeconds: 3600
              path: token
    - name: shared-config
      configMap:
        name: my-config
  additionalVolumeMounts:
    - name: aws-iam-token
      mountPath: /var/run/secrets/aws-iam
      readOnly: true
    - name: shared-config
      mountPath: /etc/app/config

A serviceAccountToken source issues a token for the session’s own service account, bound to the audience you set.

Value	Default	Description
`dataPlane.additionalVolumes`	`[]`	Kubernetes volumes added to every session pod. Each entry requires a DNS-1123 `name`.
`dataPlane.additionalVolumeMounts`	`[]`	Volume mounts added to the session container. Each entry requires `name` and an absolute `mountPath`.

At startup, the control plane checks only the shape of each entry. Kubernetes validates everything else. If Kubernetes rejects a volume or mount, session provisioning fails with a 422 response and the control plane logs the error. Changing either list restarts every running session pod once, the next time the control plane starts. Removing an entry removes its volume and mount from running sessions. With both lists empty, session pods are identical to a deployment without this option.

Code running in a session is untrusted and can be influenced by prompt injection. It can read every mounted secret, ConfigMap, volume, and token file. Assume anything you mount can reach untrusted hands, and grant mounted credentials only the permissions sessions need.

Kubernetes doesn’t catch these mistakes, so check for them yourself:

Don’t name a volume with the kube-api-access- prefix. Kubernetes treats it as the automounted cluster token volume, and dataPlane.automountServiceAccountToken stops working without an error.
Don’t use the Cake Agents internal authentication audience in a serviceAccountToken source. That mounts the session’s internal token with a longer validity window than Cake Agents allows.
Avoid mount paths under /root, /workspace, or /attachments. A nested mount hides that part of the session’s files.
Don’t mount under /var/run/secrets/cake.ai/serviceaccount. The session pod starts without working internal integrations, and a pod log warning is the only signal.

Optional: Kubernetes API rate limits

The control plane limits how fast it sends requests to the Kubernetes API server. This keeps a busy control plane from overloading a shared cluster. The defaults match the Kubernetes Go client (client-go): 5 requests per second, with bursts of up to 10. Raise the limits if session startup or status updates lag on a large cluster that can handle more traffic. Lower them if the API server is shared and other workloads see throttling. Set them with environment variables in controlPlane.deployment.extraEnv:

controlPlane:
  deployment:
    extraEnv:
      - name: K8S_API_QPS
        value: "10"
      - name: K8S_API_BURST
        value: "20"

Environment variable	Default	Description
`K8S_API_QPS`	`5`	Sustained requests per second to the Kubernetes API. Must be at least `0.5`.
`K8S_API_BURST`	`10`	Maximum requests the control plane can send at once before the per-second rate applies. Must be at least `1`.

Each control plane replica applies these limits separately. The total load on the API server is the limit multiplied by the number of replicas. The control plane fails to start if either value is below its minimum. When the API server responds with 429 Too Many Requests, the control plane retries the request automatically:

It waits for the duration in the Retry-After header when one is present. Otherwise, it backs off exponentially from 500 ms up to 30 seconds.
It retries each request up to 10 times, and waits no more than 60 seconds in total.
While it has received a 429 in the last 60 seconds, it halves both limits. The limits never drop below 0.5 requests per second and a burst of 1. Full limits return once 60 seconds pass without a 429.

The control plane also waits out 5xx responses that include a Retry-After header. If a session update still fails after these retries, the control plane logs the error and continues with other sessions. The failed update is retried later, as described in Session updates at startup.

Session updates at startup

When the control plane starts, for example after an upgrade, it checks every running session and updates any session pod whose configuration is out of date. Cake Agents queues these updates as background jobs and processes them in small batches. Running them in batches stops an upgrade from restarting every session pod at once and flooding the Kubernetes API server.

controlPlane:
  deployment:
    extraEnv:
      - name: DATA_PLANE_CONVERGE_CONCURRENCY
        value: "3"
      - name: DATA_PLANE_CONVERGE_BATCH_DELAY_SECONDS
        value: "5"

Environment variable	Default	Description
`DATA_PLANE_CONVERGE_CONCURRENCY`	`5`	Number of sessions each control plane replica updates in parallel. Must be an integer from `1` to `10`.
`DATA_PLANE_CONVERGE_BATCH_DELAY_SECONDS`	`2`	Minimum time in seconds between batches of session updates. Must be at least `0.5`.

Like the rate limits above, these limits apply to each replica separately. Lower the concurrency or raise the delay to restart fewer session pods at once. Raise the concurrency to finish upgrades faster on clusters with spare capacity. The control plane fails to start if either value is out of range. If a session update fails, Cake Agents retries it with exponential backoff, starting at 30 seconds. It retries up to 8 times, with at most 15 minutes between attempts. You don’t need to restart the control plane to retry failed updates. Session updates pause while the Kubernetes API server is rate-limiting the control plane. If the control plane has received a 429 in the last 60 seconds, each queued update waits before it calls the API server. Updates resume once 60 seconds pass without a 429. During a long pause, the control plane logs a warning every 60 seconds.

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.

Optional: Disable public ingress

Set ingress.publicServices.enabled to false when external services can’t reach your Cake Agents instance, such as in a private network or an air-gapped cluster. The default is true.

ingress:
  publicServices:
    enabled: false

When public ingress is disabled, the chart:

renders no Istio Gateway, VirtualService, or ingress-gateway AuthorizationPolicy resources
removes the Istio ingress gateway from the allowed callers of the web and storybook workloads
disables external webhooks in Cake Agents

You must route users to the control plane yourself, for example through an internal load balancer or a separately managed gateway. With external webhooks disabled, Cake Agents changes its integrations as follows:

GitHub: The GitHub App manifest registers no webhook and subscribes to no events. Cake Agents doesn’t sync the App’s webhook configuration. Agents can’t subscribe to GitHub webhook events and poll CI with the gh CLI instead.
Linear: The Linear OAuth app manifest has no webhook, and the Webhook Secret field is hidden. Linear can’t start Cake sessions, so invoking the Cake agent on a Linear issue has no effect.
Slack: The Slack app manifest has no event subscriptions. Cake Agents returns 404 for incoming Slack events.

Set this value before you register the GitHub, Linear, and Slack apps. Apps registered while webhooks were enabled keep their webhook settings until you update them in each service.

Values Reference

registry:
  # Shared fallback registry used when controlPlane/dataPlane 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.
  # Released charts (version X.Y.Z) default this to the X.Y.Z release image tag.
  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: ""
    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: ""
    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:
  # Mount a cluster-audience token so in-session tools can reach the Kubernetes API.
  automountServiceAccountToken: false
  # Existing Roles/ClusterRoles bound to every session's service account.
  # Each entry: { kind: Role | ClusterRole, name, namespace? }.
  roles: []
  # Extra Kubernetes volumes added to every session pod (full volume shape).
  additionalVolumes: []
  # Extra volume mounts for the session container. Each entry: { name, mountPath, readOnly? }.
  additionalVolumeMounts: []
  # Resources assigned to each session's data-plane container.
  # Each session starts with a memory limit equal to requests.memory.
  # limits.memory is the cap the agent can raise the limit to.
  # A session container that exceeds its current memory limit is OOM-killed and restarted.
  # limits.cpu throttles a session; it never stops the pod.
  # ephemeral-storage caps node-local disk use outside the session volume.
  # Kubernetes evicts a session pod that exceeds limits.ephemeral-storage.
  resources:
    requests:
      memory: 1Gi
      cpu: 250m
      ephemeral-storage: 1Gi
    limits:
      memory: 16Gi
      cpu: "3"
      ephemeral-storage: 10Gi
  image:
    registry: ""
    repository: cake-agents/data-plane
    tag: ""

# 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.
  clientId: ""
  pkce: true
  # Client secret from the OIDC provider. Required. Public clients without a secret aren't supported.
  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: ""

# Public ingress from external services. Set to false to render no public
# ingress resources and disable external webhooks for GitHub, Linear, and Slack.
ingress:
  publicServices:
    enabled: true

# 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

Session pod authentication

Optional: S3 object storage

Optional: Session pod resources

Session memory and CPU limits

Automatic memory resizing

Raise the memory limit

Lower the memory limit

Set the memory cap

Session disk limit

Interrupted agent turns

Optional: Session pod scheduling

Optional: Kubernetes API access from sessions

Grant the control plane permission to bind roles

Optional: Additional volumes in session pods

Optional: Kubernetes API rate limits

Session updates at startup

Optional: Custom sign-out URL

Optional: Disable public ingress

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

​Session pod authentication

​Optional: S3 object storage

​Optional: Session pod resources

​Session memory and CPU limits

​Automatic memory resizing

​Raise the memory limit

​Lower the memory limit

​Set the memory cap

​Session disk limit

​Interrupted agent turns

​Optional: Session pod scheduling

​Optional: Kubernetes API access from sessions

​Grant the control plane permission to bind roles

​Optional: Additional volumes in session pods

​Optional: Kubernetes API rate limits

​Session updates at startup

​Optional: Custom sign-out URL

​Optional: Disable public ingress

​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

Session pod authentication

Optional: S3 object storage

Optional: Session pod resources

Session memory and CPU limits

Automatic memory resizing

Raise the memory limit

Lower the memory limit

Set the memory cap

Session disk limit

Interrupted agent turns

Optional: Session pod scheduling

Optional: Kubernetes API access from sessions

Grant the control plane permission to bind roles

Optional: Additional volumes in session pods

Optional: Kubernetes API rate limits

Session updates at startup

Optional: Custom sign-out URL

Optional: Disable public ingress

Values Reference

Ingress authorization policies