# S3 storage for archived sessions Source: https://docs.cake.ai/admin/aws-storage Configure an S3-compatible bucket so Cake Agents can archive session data when users end sessions. Cake Agents can upload each archived session's persistent volume to S3-compatible object storage as a compressed archive. Configure a bucket at the organization level so users can [archive sessions](/user/archive-sessions) without losing their files. ## When to configure S3 * You want users to be able to archive sessions and retain the underlying files. * You want a durable, off-cluster copy of session data before pods and volumes are released. If S3 is not configured, archive actions still stop the session and preserve message history, but the session's files are not saved. ## Prerequisites * An S3-compatible bucket (AWS S3, or any S3-API-compatible service such as MinIO or Cloudflare R2). * Credentials available to the control plane with permission to `PutObject` into the bucket. * Admin access to Cake Agents. ## Configure S3 in the UI 1. Go to **Settings → Organization → AWS**. 2. Toggle **S3** on. 3. Fill in the fields: * **Bucket** — the bucket name. Required. * **Region** — the AWS region where the bucket lives. Defaults to `us-east-1`. * **Endpoint** — optional. Set this when using a non-AWS S3-compatible service. * **Prefix** — optional. A key prefix prepended to every object (useful for sharing a bucket across environments). 4. Save. Each archived session is uploaded under the configured prefix, keyed by session ID. ## Configure S3 with environment variables You can also configure storage on the control plane deployment using environment variables. UI values override environment variables when both are set. | Setting | Environment variable | Default | | - | - | - | | Enabled | `CAKE_S3_ENABLED` or `S3_ENABLED` | `false` | | Bucket | `CAKE_S3_BUCKET` or `S3_BUCKET` | — | | Region | `CAKE_S3_REGION`, `S3_REGION`, or `AWS_REGION` | `us-east-1` | | Endpoint | `CAKE_S3_ENDPOINT`, `S3_ENDPOINT`, or `AWS_ENDPOINT_URL_S3` | — | | Prefix | `CAKE_S3_PREFIX` or `S3_PREFIX` | `""` | Example Helm values snippet: ```yaml theme={null} env: - name: CAKE_S3_ENABLED value: "true" - name: CAKE_S3_BUCKET value: cake-agents-archives - name: CAKE_S3_REGION value: us-west-2 - name: CAKE_S3_PREFIX value: prod/ ``` Provide AWS credentials via the standard AWS SDK mechanisms (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`, an instance role, IRSA on EKS, or Workload Identity). ## What gets uploaded For each archived session, Cake Agents packages the session's persistent volume into a compressed tarball and uploads it to: ``` s3:///.tar.gz ``` Message history is stored in the database, not in S3. # Getting Started with the Console Source: https://docs.cake.ai/admin/getting-started-console For existing Cake platform customers: sign up for the Cake Console, skip the free trial, and register a Kubernetes instance. This guide is for existing Cake platform customers who want to run Cake Agents on their own Kubernetes cluster. It walks you through signing up for the Cake Console, skipping the free-trial welcome flow, and registering a Kubernetes instance. > [!TIP] > > New to Cake? Go straight to [console.cake.ai](https://console.cake.ai) to start a free trial. ## What You Need * A working Kubernetes cluster (1.27 or later) * A public hostname for the instance, for example `agents.cake.example.com`, with a DNS record pointing at your cluster's ingress * An ingress controller or gateway (Istio, NGINX, AWS ALB, etc.) Cake Support runs the Helm install, database, and registry access for you. You only need to submit your AWS account ID and create the instance with the right hostname, then finish registration in the Console. ## The Roles: Console and Instance * The **Console** (`console.cake.ai`) is Cake's management plane. It holds your organization, your instances, AWS account grants, and team members. You sign up here and register instances from here. * An **instance** is a single Cake Agents deployment (the control plane) that runs in your cluster, identified by its public URL. That is where your team actually creates and uses sessions. Signing up for the Console and registering an instance are two separate steps. You do the first in the Console and complete the second with a short handshake between the two. ## 1. Sign Up for the Console 1. Open [console.cake.ai/signup](https://console.cake.ai/signup). If a teammate invited you, open the link in the invitation email instead. 2. Enter your name and work email, and accept the Terms of Use and Privacy Policy. 3. Select **Email me the link**. Cake sends a sign-up link to your email (no password). 4. Open the link in the email. You land on the welcome flow. 5. Select **Complete signup** to finish creating your account. You are now signed in to the Console. > [!NOTE] > > New signups must use a work email address. The Console rejects personal addresses such as `gmail.com` and `googlemail.com`. It also rejects temporary or disposable addresses such as `mailinator.com` and `yopmail.com`. If you use one of these, the Console shows "Please use your work email" and does not send a sign-up link. Existing accounts on these domains can still sign in. ## 2. Skip the Free-Trial Welcome Flow The welcome flow offers two ways to get a first instance: * **Hosted by Cake** — Cake runs a free trial instance for you. * **In your AWS account** — Cake installs into your own AWS account. You are registering your own Kubernetes instance, so pick the second option: 1. On **Choose your free trial**, select **In your AWS account**, then select **Start 14-day free trial**. 2. On **Here's what happens next**, select **Continue**. 3. On **What's your AWS account ID?**, enter the 12-digit account ID of the AWS account that runs your cluster. Find it with: ```bash theme={null} aws sts get-caller-identity --query Account --output text ``` Then select **Continue**. This authorizes your account to pull Cake's container images from our private ECR registry. The **Setting up access** step runs automatically, and the flow ends on **Setup complete**. > [!NOTE] > > The **Skip setup for now** link on this step drops you to the Console dashboard instead. The dashboard then shows a "finish setup" nudge, and you can submit the account ID any time from the **AWS access** section. ## 3. Create Your Instance From the **Setup complete** step, select **Continue to install**. (You can also start here later from the **Add instance** button on the Console dashboard.) 1. On **Choose an install method**, select **Existing Kubernetes**, then select **Continue with Existing Kubernetes**. 2. On **Choose your hostname**, enter the public hostname you will route to this install, for example `agents.cake.example.com`, or a full URL with a path prefix if the instance lives under a shared host (for example `https://hosted.cake.ai/acme`). Cake-managed DNS is not used for Existing Kubernetes installs, so make sure your DNS record points at your cluster's ingress. 3. Select **Continue**. Cake Support finishes the install from here — Helm, database, and registry access — so there's nothing more to run locally. Keep the instance's page open; it shows the install status. ## 4. Finish Registration in the Console Once the install is done, open your instance URL in a browser. Because the instance isn't registered yet, it shows a **Register your instance** page instead of the app. 1. Select **Register in Console**. 2. The Console verifies the deployment and mints its credentials, then returns to a **Finish Setup** page. 3. Select **Log in to your instance**. The instance uses the credentials to set itself up and creates an initial admin account from your Console profile. You are sent to a sign-in link for the instance's first administrator. Sign in, and Cake Agents is ready to use. ## What's Next With a registered instance, configure the integrations your team needs: * [Set Up GitHub](./github-setup) * [Configure Model Providers](./model-providers) * [Core Concepts](/core-concepts) If you'd rather manage the cluster install end to end yourself, see [Getting Started with Kubernetes](./getting-started-kubernetes). # Getting Started with Kubernetes Source: https://docs.cake.ai/admin/getting-started-kubernetes Install Cake Agents directly into an existing Kubernetes environment with Helm. 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 Architecture](https://mintcdn.com/cake-57b50798/lJXV0ip7aoTQt6lf/images/architecture-diagram.png?fit=max\&auto=format\&n=lJXV0ip7aoTQt6lf\&q=85\&s=7fd55d22c382b64594bd3222acccc2f4) 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](/core-concepts#data-plane-authentication) * 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: ```yaml theme={null} externalDatabase: existingSecret: cake-agents-db existingSecretKey: DATABASE_URL postgresql: enabled: false ``` If manually provisioning this secret, you may want to first create the namespace. ```bash theme={null} kubectl create namespace cake-agents ``` Then apply a secret manifest that looks like this: ```yaml theme={null} 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](#header-auth) via trusted headers. In your OIDC provider, create a new client with these settings: * Client type: Confidential * Redirect URI: `https:///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. ```yaml theme={null} kind: Secret apiVersion: v1 metadata: name: sso-oidc namespace: cake-agents type: Opaque stringData: clientSecret: ``` ## Minimal Values File Start from a small values file and expand from there: ```yaml theme={null} 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: 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: ```bash theme={null} helm show chart oci://public.ecr.aws/kflow/charts/cake-agents --version 0.5.0 ``` Install the chart with your values file: ```bash theme={null} 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: * [GitHub setup](./github-setup) * [Model provider setup](./model-providers) ## Session pod authentication Session pods authenticate to the control plane with per-session service account tokens. See [Data plane authentication](/core-concepts#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` ```yaml theme={null} 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: ```yaml theme={null} 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](#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](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) block, so you can set both requests and limits: ```yaml theme={null} 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](#interrupted-agent-turns) 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](#set-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: 1. Go to **Settings → Organization → Sessions**. 2. In **Max Memory**, enter a whole number and select **Mi** or **Gi**. 3. 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](/admin/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: ```yaml theme={null} 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. > [!WARNING] > > 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](#interrupted-agent-turns). > [!NOTE] > > 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](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) 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: ```yaml theme={null} 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`. > [!WARNING] > > 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](#interrupted-agent-turns). ## 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. ```yaml theme={null} 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: 1. Create the Role or ClusterRole in the cluster, outside the Cake Agents release. 2. Give the control plane service account `create`, `get`, `list`, and `delete` on `rolebindings` in every target namespace. 3. 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: ```yaml theme={null} 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. > [!WARNING] > > 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. > [!NOTE] > > 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. > [!WARNING] > > 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)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) token so in-session tools can assume an AWS role. * `dataPlane.additionalVolumes` takes a list of standard Kubernetes [volumes](https://kubernetes.io/docs/concepts/storage/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: ```yaml theme={null} 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. > [!WARNING] > > 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`: ```yaml theme={null} 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). ### 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. ```yaml theme={null} 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: ```yaml theme={null} 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`. ```yaml theme={null} 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](/user/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 ```yaml theme={null} 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. # Set Up GitHub Source: https://docs.cake.ai/admin/github-setup Register and configure GitHub access for Cake Agents administrators. Administrators set up GitHub once for the Cake Agents environment. Individual users then [link their own GitHub accounts](../user/link-github) separately. ## What This Enables GitHub setup allows Cake Agents to: * open pull requests * push commits on behalf of linked users * use GitHub-backed workflows inside sessions ## Admin Responsibilities As an admin, you are responsible for: * registering the GitHub App used by Cake Agents * configuring the app so the control plane can complete the user linking flow * ensuring the environment can store the app credentials securely ## Requirements You must be an organization-level admin on GitHub to proceed. ## Instructions ### Register the GitHub App 1. In Cake Agents, go to `Settings → Organization → Integrations`. 2. Next to **GitHub**, select **Connect**. 3. Enter the name of your GitHub organization. We will use this to create a GitHub App for your organization's instance of Cake Agents. 4. Click "Continue to GitHub". 5. For "GitHub App name" append your company name. For example "Cake Agents - ACME Corp". 6. Click "Create GitHub App for \ ## Install the GitHub App 1. Back in Cake Agents, navigate to `Settings → Organization → Integrations` and select **Connect** next to GitHub. 2. Click "Continue to GitHub". 3. Select the repositories you'd like to enable (this can be changed later), then click "Install". ## Webhook events The GitHub App that Cake Agents registers sends repository webhook events, such as CI results and pull request activity, to Cake Agents. Agents use these events to [watch CI and react to GitHub activity](/user/github-webhook-events) inside sessions. If your deployment [disables public ingress](/admin/getting-started-kubernetes#optional-disable-public-ingress), Cake Agents registers the App without a webhook or event subscriptions. The GitHub settings page shows **External webhooks are disabled** instead of the webhook configuration status. Apps registered before webhook support might not subscribe to these events. If an agent reports that the App doesn't subscribe to a requested event, enable that event on the App's **Permissions & events** page in GitHub. ### Webhook configuration sync When you open the GitHub settings under `Settings → Organization → Integrations`, Cake Agents checks the App's webhook configuration on GitHub. If the webhook URL, content type, or secret differs from what Cake Agents expects, Cake Agents updates them on GitHub automatically. This keeps deliveries working after your deployment URL changes. The page shows one of the following states: | Status | What to do | | - | - | | **The app's webhook configuration on GitHub matches Cake** | Nothing. The webhook URL, JSON content type, and secret are in sync. | | **The app's webhook configuration on GitHub differs from Cake** | Select **Retry sync**. | | **The webhook configuration could not be re-verified on GitHub** | Select **Retry sync**. | | **The app's webhook configuration on GitHub could not be read** | GitHub didn't respond or rejected the request. Reload the page later. | | **The GitHub App registration has no stored webhook secret** | Cake Agents can't verify webhook signatures or sync the configuration until the registration has a stored webhook secret. | | **N webhook events are not subscribed on GitHub** | Select **Subscribe to events on GitHub** and enable the listed events. | Cake Agents can't change some settings because GitHub doesn't expose them through its API. Set these manually in the App's settings on GitHub: * the webhook **Active** checkbox * event subscriptions on the **Permissions & events** page * SSL verification. Cake Agents shows a warning if SSL verification is disabled. ## Test the integration You can test the integration by [linking your GitHub account to your Cake Agents user](/user/link-github) and verifying that the New Session page shows all the expected GitHub repos. # Impersonate users to troubleshoot their Cake Agents view Source: https://docs.cake.ai/admin/impersonate-users Sign in as another user from Organization Settings to reproduce issues and see exactly what they see. Learn how to start and stop impersonating safely. As an administrator, you can impersonate another user in your organization. While you impersonate someone, Cake Agents shows the app exactly as they see it. Use this to reproduce a problem a user reports or to check their sessions and settings. > [!WARNING] > > Anything you do while impersonating is attributed to the user you impersonate. That includes creating sessions, sending messages, and changing settings. ## When to impersonate a user * A user reports a problem you can't reproduce from your own account. * You need to confirm what a user can see, such as their session list or connected integrations. ## Prerequisites * You are signed in as an administrator. ## Start impersonating 1. Open `Settings → Organization → Users`. 2. Select the actions menu next to the user you want to impersonate. 3. Select **Impersonate**. 4. In the confirmation dialog, select **Impersonate**. Cake Agents switches you to that user's account and shows a notification that confirms the switch. The **Impersonate** action doesn't appear for your own account. It also doesn't appear while you are already impersonating someone. ## While you impersonate An orange **Impersonating** notice floats over the app. The notice shows the name and email of the user you impersonate and the admin account you signed in with. * Drag the notice by its handle to move it. You can also focus the handle and move it with the arrow keys. * Select the minimize button to collapse the notice to a single line. Your user menu also shows an **Impersonating** label. ## Stop impersonating Do any of the following: * Select **Stop impersonating** in the impersonation notice. * Select the **Stop impersonating** icon in the minimized notice. * Open your user menu and select **Stop impersonating**. Cake Agents returns you to your own admin account. An impersonation session ends automatically after 8 hours. ## Limits * You can't impersonate someone while you are already impersonating another user. Stop impersonating first. * Only `@cake.ai` administrators can impersonate a `@cake.ai` administrator. * While you impersonate a user, you have their permissions, not your own. # Set up Jira Source: https://docs.cake.ai/admin/jira-setup Connect Cake Agents to Atlassian so sessions can read and update Jira work through the Atlassian MCP server. Administrators connect Atlassian once for the whole organization. After setup, each user connects their own Atlassian account, and their sessions can work with Jira through the official Atlassian MCP server. ## What this enables Once a user connects their Atlassian account, agents in their sessions can: * search and read Jira issues, comments, and projects * create and update issues and add comments * use other consented Atlassian apps (for example Confluence) through the same connection Agents act with the connecting user's own Atlassian permissions. ## Requirements * You need the **admin** role in Cake Agents. * An **Atlassian organization admin** must authorize the Cake Agents domain before anyone can complete the Atlassian consent screen. Cake identifies itself to Atlassian with a Client ID Metadata Document hosted on its own domain, and Atlassian blocks consent from custom domains until an admin allows them: 1. Go to [Atlassian Administration](https://admin.atlassian.com) and select your organization. 2. Select **Connectors**, then **Atlassian MCP server**. 3. Select **Add domain** and add the domain of your Cake Agents deployment — the host of the URL you use to open Cake Agents, for example `cake-agents.example.com`. Domain settings apply to the whole Atlassian organization. OAuth 2.1 is Atlassian's default authentication method for the MCP server, so no other connector setting needs to change. * Each user needs access to the Atlassian site they select at consent. ## Instructions ### Add the Atlassian MCP server 1. In Cake Agents, go to `Settings → Organization → MCP Connectors`. 2. Under **Add an MCP server**, enter: * **Name:** `atlassian` — this prefixes the tools agents see, for example `atlassian.search`. Pick a short, unique name; see [Choose a name](/admin/mcp-servers#choose-a-name). * **URL:** `https://mcp.atlassian.com/v2/mcp` — the canonical Atlassian MCP endpoint. Older `v1` URLs are not supported. 3. Select **Add server**. Cake contacts Atlassian and registers itself as an OAuth client before saving; if registration fails, Cake shows the reason and does not save the server. ### Connect user accounts Each user then connects their own Atlassian account in `Settings → User → MCP Connectors`. See [Connect to MCP servers](/user/mcp-connectors). At consent, the user picks their Atlassian site and approves the requested permissions. > [!NOTE] > > Cake requests the scopes the Atlassian MCP server advertises, so the consent screen spans multiple Atlassian apps and includes write, manage, and delete permissions. There is no Jira-only isolation. When a user messages a session, the agent can call Atlassian tools through the Cake MCP server. The agent uses the connections of the last user who sent a message to the session; if nobody has sent a message yet, it uses the session creator's connections. ## Remove the integration Removing the Atlassian server in `Settings → Organization → MCP Connectors` deletes every user's saved Atlassian connection. Re-adding the server requires every user to connect again. A user can disconnect only their own account in `Settings → User → MCP Connectors` without affecting anyone else. ## Troubleshooting ### Atlassian blocks the consent screen The Cake Agents domain is not authorized in your Atlassian organization, or an org policy blocks the connection. Add the domain under Atlassian Administration → Connectors → Atlassian MCP server → Domains (see [Requirements](#requirements)), and check the user's site access and the org's OAuth and IP-allowlist policies. ### Registration fails or tools never appear after a `v1` URL was used Only the canonical v2 endpoint `https://mcp.atlassian.com/v2/mcp` is supported. If the server was registered with a `v1` URL, remove it in `Settings → Organization → MCP Connectors` and add the v2 URL instead; users then reconnect their accounts. ### No Atlassian tools in a session The user has not connected their own Atlassian account — org registration alone is not enough. Connect in `Settings → User → MCP Connectors`. Transient Atlassian throttling can also interrupt consent or tool calls; retry before changing configuration. ## Not supported Jira events cannot start Cake sessions — the Atlassian MCP server exposes tools only, with no webhook channel. For issue-triggered sessions, see [Set up Linear](/admin/linear-setup). # Set up Linear Source: https://docs.cake.ai/admin/linear-setup Connect Cake Agents to Linear so sessions can read issues and post updates. Administrators connect Linear to Cake Agents once for the whole organization. After setup, sessions can read Linear issues and projects and post progress back as comments. ## What this enables Connecting Linear allows Cake Agents to: * read issues, projects, and status * comment on issues with session progress * move issues when a pull request is opened or merged * start a Cake session automatically when a user invokes the Cake agent on a Linear issue ## How Linear-triggered sessions work Once the integration is configured, invoking the Cake agent on an issue in Linear creates a new Cake session. The session is titled after the issue (for example, `[ENG-123] Fix login redirect`) and is owned by the Linear user who triggered it. Cake replies once in the Linear agent session with a link to the new Cake session, and the rest of the conversation happens in Cake Agents rather than in Linear. The Linear user must already exist in Cake Agents with the same email address. If no matching Cake user is found, the session is not created. Ask users to sign in to Cake Agents at least once before invoking the agent from Linear. ## Admin responsibilities As an admin, you are responsible for: * creating an OAuth application in your Linear workspace * pasting the Client ID, Client Secret, and Webhook Secret Linear generates into Cake Agents * installing Cake Agents into your Linear workspace * keeping the credentials up to date if you rotate them ## Requirements * You must be a Linear workspace admin to create the OAuth application. * The Linear OAuth application must have client credentials tokens enabled. Cake Agents uses Linear's `client_credentials` grant to authenticate as the app. The **Create OAuth App in Linear** button enables this for you. If you created the application manually, enable client credentials in the app's settings in Linear. ## Instructions ### Create the OAuth app in Linear 1. In Cake Agents, go to `Settings → Organization → Integrations`. 2. Next to **Linear**, select **Connect**. 3. In the dialog, select **Create OAuth App in Linear**. This opens Linear's new-application page with your callback URL and webhook URL prefilled from a manifest — you do not need to copy them by hand. 4. In Linear, review the app details and create the application. 5. Linear returns a **Client ID**, **Client Secret**, and **Webhook Secret** on the app's settings page. The Webhook Secret is what Cake Agents uses to verify incoming Linear webhook requests, so make sure to copy it before leaving the page. ### Save the credentials in Cake Agents 1. Return to the **Connect Linear** dialog in Cake Agents. This is the **Configure** step of the setup wizard. 2. Paste the **Client ID** into the Client ID field. 3. Paste the **Client Secret** into the Client Secret field. 4. Paste the **Webhook Secret** into the Webhook Secret field. 5. Select **Save and continue**. > [!NOTE] > > If your deployment [disables public ingress](/admin/getting-started-kubernetes#optional-disable-public-ingress), the Linear app has no webhook and Cake Agents hides the Webhook Secret field. Linear can't start Cake sessions from issues on these deployments. Saving new credentials replaces any previous values. ### Install Cake Agents in your Linear workspace Saving credentials moves the wizard to the **Install** step. This step connects a Linear workspace to Cake Agents so the app can act on issues. 1. On the **Install** step, select **Install Cake Agents in Linear**. Linear opens in a new tab and asks you to authorize the app for your workspace. 2. Review the requested permissions (read issues and projects, assignable to issues) and approve the installation in Linear. 3. Return to Cake Agents. The dialog shows **Linear workspace connected** with the workspace URL and the profile Cake Agents installed as. 4. Select **Done** to close the dialog. Only one Linear workspace can be connected at a time. To connect a different workspace, install Cake Agents from that workspace using the same button — the previous installation is replaced. ## Rotate or update credentials To rotate a secret or point Cake Agents at a different Linear application: 1. Generate a new Client Secret or Webhook Secret in Linear (or create a new application). 2. In Cake Agents, go to `Settings → Organization → Integrations` and select **Connected** next to Linear. 3. On the **Configure** step, enter the Client ID, Client Secret, and Webhook Secret, then select **Save and continue**. 4. If you switched to a different Linear application, reinstall Cake Agents on the **Install** step. ## Troubleshooting ### Linear app does not support the client\_credentials grant type The **Install** step shows this error when the Linear OAuth application does not allow client credentials tokens. To fix it: 1. Open your application in [Linear's API settings](https://linear.app/settings/api/applications). 2. Enable client credentials tokens for the application and save. 3. Reopen the **Connect Linear** dialog in Cake Agents. ### Configured Linear app belongs to a different workspace The **Install** step shows this error when the saved credentials belong to a Linear app in a different workspace than the one that is currently installed. Either restore the original Linear app credentials on the **Configure** step, or reinstall Cake Agents from the new workspace on the **Install** step. # Add MCP servers for your organization Source: https://docs.cake.ai/admin/mcp-servers Add remote MCP servers to Cake Agents so agents can call their tools. Each user then connects their own account through OAuth from the settings page. MCP (Model Context Protocol) servers expose tools that agents can call, such as searching a Notion workspace or reading tickets from an issue tracker. Administrators choose which remote MCP servers are available to the organization. Each user then connects their own account to those servers, so agents act with that user's permissions. ## How it works 1. An admin adds an MCP server in **Organization settings → MCP Connectors**. 2. Cake registers itself with the server as an OAuth client. 3. Each user connects their own account in **User settings → MCP Connectors**. See [Connect to MCP servers](/user/mcp-connectors). 4. When that user messages a session, the agent can call the server's tools through the Cake MCP server. The agent uses the connections of the last user who sent a message to the session. If nobody has sent a message yet, it uses the session creator's connections. ## Requirements The server must meet these requirements before Cake can add it: * It is a remote MCP server that uses the Streamable HTTP transport. * Its URL is an absolute `https://` URL of up to 2,048 characters, with no embedded credentials (`user:pass@`) and no fragment (`#...`). * It supports OAuth authorization and publishes protected-resource metadata. * Its authorization server supports automatic client registration through Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR). * Cake can reach it under your egress policy. ## Add a server You need the **admin** role. 1. Open **Organization settings → MCP Connectors**. 2. Under **Add an MCP server**, enter a **Name**, for example `Notion`. 3. Enter the server **URL**, for example `https://mcp.example.com/mcp`. 4. Select **Add server**. Cake contacts the server and registers as an OAuth client before it saves the server. If registration fails, Cake doesn't save the server and shows the reason under the form. After Cake saves the server, users can connect to it. Running sessions pick up the server's tools when users connect, without starting a new session. | Message | What it means | | - | - | | Not an MCP server | The URL doesn't serve MCP protected-resource metadata. Check that you entered the MCP endpoint, not the provider's website. | | This MCP server doesn't support automatic OAuth registration | The authorization server supports neither CIMD nor DCR. | | Cake couldn't register with this MCP server | The authorization server rejected Cake's registration request. | | The MCP server or its authorization server is unreachable under the egress policy | Your network policy blocks Cake from reaching the server. | | The MCP server or its authorization server rejected the registration | The upstream server returned an error. Try again later. | ### Choose a name The name labels the server in settings and prefixes its tools for agents. Agents see each tool as `.`. For example, a `search` tool on a server named `Notion` appears as `Notion.search`. Names are case-sensitive. Pick a short, unique name for each server, because Cake rejects tool calls when two servers share a name. ### Register a server from an agent link A user might ask an agent for help with a service your organization hasn't registered. If the agent knows the service's MCP endpoint, it gives the user a registration link to pass to you. The link opens **Organization settings → MCP Connectors** with the **URL** field already filled in. If the agent also knows the service's name, the link fills in the **Name** field too. Review the values. Then select **Add server**. Cake runs the same checks as when you add a server by hand. The link points to the settings page with the values in its query string, for example: ```text theme={null} https:///settings/org/mcp-servers?name=Notion&url=https%3A%2F%2Fmcp.example.com%2Fmcp ``` After you add the server, the user can connect their account. See [Connect your account to MCP servers](/user/mcp-connectors). ## Remove a server 1. Open **Organization settings → MCP Connectors**. 2. Select the trash icon next to the server. 3. Select **Remove server** to confirm. Agents lose access to the server immediately. You can't undo this. To restore access, add the server again and ask users to reconnect. # Configure Model Providers Source: https://docs.cake.ai/admin/model-providers Add and maintain the providers and models available to Cake Agents sessions. Providers are configured by administrators in the Cake Agents settings UI and made available to user sessions. ## What You Configure Providers define which OpenCode providers and models Cake Agents can use for session execution. They typically include: * provider identity * display name * base URL or endpoint * authentication details such as API keys or auth headers * the list of models users may select Cake passes these provider definitions into the OpenCode runtime for each session. For the provider schema and provider-specific examples, see the [OpenCode providers documentation](https://opencode.ai/docs/providers/). ## How Cake Uses Providers When a session starts, Cake builds the OpenCode configuration for that session from the providers currently configured in the control plane. That means: * providers are managed centrally * sessions use the approved provider definitions * users can only pick from models that admins have configured If no providers are configured, users cannot start sessions. ## Configure Providers in the UI 1. Sign in to Cake Agents as an administrator. 2. Open `Settings → Organization`. 3. Navigate to `Providers`. 4. Add or edit the provider JSON configuration. 5. Enter the provider details you want to expose. 6. Add any required secrets such as API keys or authorization headers. 7. Define the models that users should be able to select. 8. Save the provider configuration. 9. Create a test session and verify the expected models appear in the model picker. ## Recommended Workflow 1. Decide which provider backends you want to expose. 2. Start from the provider format documented by OpenCode. 3. Add only the models you intend users to access. 4. Save the configuration in `Settings → Organization → Providers`. 5. Verify that new sessions can start successfully. ## Example Configurations Anthropic example: ```json theme={null} { "anthropic": { "models": { "claude-sonnet-4-6": {} }, "npm": "@ai-sdk/anthropic", "options": { "apiKey": "%%SECRET%%" } } } ``` OpenAI example: ```json theme={null} { "openai": { "models": { "gpt-5": {}, "gpt-5-mini": {} }, "npm": "@ai-sdk/openai", "options": { "apiKey": "%%SECRET%%" } } } ``` In these examples: * the top-level key is the provider ID * `models` defines the models users can choose from * `npm` selects the OpenCode provider package * `options` contains provider-specific configuration such as the API key Use the redacted `%%SECRET%%` placeholder in the UI when editing an existing saved secret value. If your settings UI supports separate secret fields, prefer storing API keys and auth headers as secrets rather than inline JSON. ## LiteLLM Gotchas If you are using LiteLLM as a proxy in front of multiple upstream providers (OpenAI, Anthropic, etc.), configure a separate Cake provider entry for each upstream provider. Each provider entry must use the corresponding `npm` package for that upstream, even if the `baseURL` points at the same LiteLLM instance. Example (two providers that both route through the same LiteLLM base URL): ```json theme={null} { "litellm-openai": { "models": { "openai/gpt-5.2": {}, "openai/gpt-5.4": {} }, "npm": "@ai-sdk/openai", "options": { "apiKey": "%%SECRET%%", "baseURL": "http://litellm.example.com/v1" } }, "litellm-anthropic": { "models": { "claude-opus-4-6": {}, "claude-sonnet-4-6": {}, "claude-sonnet-4-7": {} }, "npm": "@ai-sdk/anthropic", "options": { "apiKey": "%%SECRET%%", "baseURL": "http://litellm.example.com/v1" } } } ``` ## Operational Notes * Treat provider credentials as environment-scoped secrets. * Limit the available models to the set you want users to rely on. * Review provider settings whenever endpoint URLs, auth material, or model names change. * Test session creation after any provider change. * To cap context and output sizes for the configured models, see [Configure token limits](/admin/token-limits). # Session volume autoscaling Source: https://docs.cake.ai/admin/session-volume-autoscaling Automatically expand session persistent volumes when disk usage crosses a configurable high watermark on EKS clusters. Cake Agents can automatically grow each session's persistent volume as it fills up. The control plane periodically reads disk usage for every running session from the kubelet and expands the session's PersistentVolumeClaim when usage crosses a high watermark. Autoscaling is enabled by default in the Helm chart. ## Why autoscaling helps * Sessions clone large repositories or produce build artifacts that outgrow the initial volume size. * You want to keep `sessionVolume.initialSize` small and pay only for storage that sessions actually use. See the [Helm values reference](/admin/getting-started-kubernetes#values-reference) for the `sessionVolume` block. If autoscaling is disabled, sessions keep their initial volume size and can run out of disk space during long or storage-heavy work. ## When to disable autoscaling Set `diskAutoscale.enabled: false` when your cluster cannot meet the prerequisites below, such as clusters that are not on EKS or that lack kubelet fine-grained authorization. ## Prerequisites * An EKS cluster with kubelet fine-grained authorization enabled. The control plane reads volume telemetry directly from each node's kubelet, which must accept the control plane's service account token. * A StorageClass with `allowVolumeExpansion: true` for session volumes. Cake Agents skips expansion when the StorageClass does not allow it. * `rbac.enabled: true` in the Helm chart. When autoscaling is enabled, the chart adds a ClusterRole that grants the control plane `get` on `nodes/metrics` and `storageclasses`. ## Configure with Helm values Tune or disable autoscaling through the `diskAutoscale` block: ```yaml theme={null} diskAutoscale: enabled: true # How often the control plane checks session volumes (cron syntax). cronExpression: '* * * * *' # Expand when used bytes exceed this fraction of the volume's current size. highWatermarkRatio: 0.9 # Target size multiplier applied to current usage when expanding. scaleFactor: 1.5 # Smallest amount a volume grows in a single expansion. minIncrement: 1Gi # Volumes never grow beyond this size. maxVolumeSize: 128Gi ``` | Value | Default | Description | | - | - | - | | `enabled` | `true` | Turns session volume autoscaling on or off. | | `cronExpression` | `* * * * *` | Reconciliation schedule. The default checks every minute. | | `highWatermarkRatio` | `0.9` | Usage threshold that triggers expansion. Must be between 0 and 1, exclusive. | | `scaleFactor` | `1.5` | Multiplier applied to current usage to compute the new size. Must be greater than 1. | | `minIncrement` | `1Gi` | Minimum growth per expansion, as a Kubernetes storage quantity (`Ki`, `Mi`, `Gi`, `Ti`, `Pi`, `Ei`). | | `maxVolumeSize` | `128Gi` | Hard cap on any session volume's size. | The chart maps these values to `SESSION_DISK_AUTOSCALE_*` environment variables on the control plane. The control plane validates the configuration at startup and rejects invalid ratios, scale factors, storage quantities, and cron expressions. ## Configure in the UI You can also manage autoscaling from the organization settings: 1. Go to **Settings → Organization → Sessions**. 2. In the **Autoscaling** section, make sure **Enabled** is toggled on. 3. Adjust the fields: * **Starting Volume Size** — the size each new session volume starts at. Whole GiB values only, at least 1 Gi, and no larger than the max volume size. Applies to newly created sessions. * **High Watermark Ratio** — usage fraction that triggers expansion. Must be between 0 and 1, exclusive. * **Max Volume Size** — hard cap on any session volume's size. Must be at least 1 Gi. * **Minimum Increment** — smallest amount a volume grows in a single expansion. * **Scale Factor** — multiplier applied to current usage to compute the new size. Must be greater than 1. 4. Select **Save**. Changes apply only when you save. The form validates all fields together and rejects a starting volume size that exceeds the max volume size. Saved changes take effect on the next scheduled reconciliation run without a control plane restart. ### Settings precedence * Until you save autoscaling settings in the UI, the control plane uses the Helm values (`diskAutoscale` and `sessionVolume.initialSize`). * Before your first save, the **Autoscaling** section shows these Helm values. If `diskAutoscale.enabled` is `true`, the section appears enabled and its fields show the effective configuration. Sizes in units other than Mi or Gi, such as `2Ti`, appear converted to Gi. * Once saved, UI settings replace the Helm values for the expansion policy and the starting volume size. * Disabling autoscaling in the UI turns it off even when `diskAutoscale.enabled` is `true` in Helm. * The reconciliation schedule (`cronExpression`) always comes from Helm. ## How expansion works On each scheduled run, the control plane: 1. Lists running session pods and collects filesystem telemetry for each session volume from the node's kubelet. Stale or malformed telemetry is rejected and logged, and that volume is skipped for the run. 2. Compares used bytes against the volume's current size. Volumes below `highWatermarkRatio` are left unchanged. 3. Computes the new size as the larger of `current size + minIncrement` and `used bytes × scaleFactor`, capped at `maxVolumeSize`. 4. Patches the PersistentVolumeClaim with the new size. The storage provider then expands the underlying volume. Volumes already at `maxVolumeSize` are never expanded further. Expansion is one-way: Cake Agents never shrinks a session volume. ## Autoscaling inside sessions `/workspace` and the home directory (`/root`) are both backed by the session volume and survive restarts. Files anywhere else, such as `/tmp`, are ephemeral. The default agent prompt instructs agents to keep important files under `/workspace`. Because the home directory shares the session volume, package manager caches such as `~/.npm` and `~/.cache` count toward its usage and can trigger expansion. Archiving a session uploads `/workspace`, session history, and attachments, but not the home directory. When autoscaling is enabled, session agents also get a `wait_for_volume_autoscale` tool. If a write to `/workspace` fails because the disk is full, the agent can call this tool to wait for the volume to grow, then retry. The tool: * Waits up to a configurable timeout (default 300 seconds, maximum 900) and returns as soon as `/workspace` capacity has grown. * Returns immediately with the reason and suggested next steps when the autoscaler decides not to expand, for example when usage is below the high watermark, the volume is at its maximum size, or the StorageClass does not allow expansion. * Reports that autoscaling is disabled if it was turned off after the session started. The tool is only registered in sessions created while autoscaling is enabled. ### Expansion progress in the session view Users can follow storage expansions directly in the session: * **While an expansion runs**, a progress indicator appears at the bottom of the message history, above the message box. It shows the current and target volume sizes, for example `Disk hit 90% · autoscaling storage 10.7 GB → 16.1 GB`. The percentage reflects the configured high watermark ratio. * **After an expansion completes**, the indicator disappears. Cake Agents adds a divider to the session history that records the change and when it finished, for example `Storage autoscaled 10.7 GB → 16.1 GB`, followed by the completion time. Completed expansion entries stay in the session history, so you can see every time the session's volume grew. Sizes appear in decimal units, so a `10Gi` volume displays as `10.7 GB`. ### Resuming after expansion A full volume can interrupt the agent's current turn and leave the session stalled with its task unfinished. After an expansion finishes, the control plane posts a synthetic `Autoscaling completed` message to the session. This message prompts the agent to pick up the interrupted task without any action from you. If the agent was not interrupted, it can ignore the message. The control plane sends this message once per expansion. If the session is still starting or cannot receive the message, the control plane retries on later reconciliation runs for up to 30 minutes. It stops retrying if the session is archived or deleted. # Configure the Small Model Source: https://docs.cake.ai/admin/small-model Select the lightweight model Cake Agents uses for background tasks like session title generation. The small model is the lightweight model Cake Agents uses for background tasks that do not require the default model's full capabilities. The most common use is auto-generating a session's title from its first message. Picking a fast, low-cost model here keeps those background tasks quick and cheap without affecting the model that runs your sessions. ## Prerequisites * You are signed in as an administrator. * At least one provider is configured with at least one model. See [Configure Model Providers](/admin/model-providers). ## Configure the Small Model 1. Sign in to Cake Agents as an administrator. 2. Open `Settings → Organization → General`. 3. Under `Small model`, pick a model from the dropdown. 4. The selection saves automatically. The small model is a required setting and is shared across the whole organization. Any model exposed by your configured providers is a valid choice. ## How Cake Uses the Small Model When Cake builds the OpenCode configuration for a session, it passes the selected model as `small_model`. OpenCode uses it for internal, lightweight calls such as generating a session title. Your main conversation continues to use the [Default model](/admin/model-providers) or whichever model the user picked for that session. ## Recommendations * Choose a small, fast, inexpensive model from the same provider you already use for the default model. * Do not point the small model at a large reasoning model. Session titles and other background tasks do not benefit from it, and every new session pays the cost. * If you retire a model or change providers, update the small model selection so it keeps pointing at a model your providers still expose. # Configure token limits Source: https://docs.cake.ai/admin/token-limits Set global and per-model context and output token limits that apply to every Cake Agents session in your organization. Token limits cap the context window and output size, in tokens, that sessions use for each model. Administrators set them once, and every new session applies them automatically. Use token limits when you want to: * Constrain context growth to control cost per session. * Keep sessions within the context window a proxy or upstream provider actually supports. * Give specific models a larger or smaller budget than the rest. ## How limits are resolved When a session starts, Cake resolves the context and output limits for its model in this order: 1. A per-session override, if the user set one when creating the session. Admins can always set one. Other users can only set one when [non-admin overrides](#allow-non-admin-overrides) are on. 2. A per-model override from the Token Limits settings. 3. The global limit from the Token Limits settings. If none of these are set, the model runs without a configured limit. Cake passes the resolved values into the OpenCode model configuration as `limit.context` and `limit.output`. ## Set limits in the UI 1. Sign in to Cake Agents as an administrator. 2. Open `Settings → Organization → Providers`. 3. Scroll to the `Token Limits` section. 4. Enter a global `Context Limit` and `Output Limit`. 5. Optionally add per-model overrides for models that need different values. 6. Save the settings. ## Allow non-admin overrides A context limit is a spend control, so by default only administrators can override token limits for a single session. To let every user in your organization set per-session limits: 1. Open `Settings → Organization → Providers` and scroll to the `Token Limits` section. 2. Turn on **Allow non-admin overrides**. Cake saves the change immediately. When the switch is off, users who are not admins don't see the token limits control on the New Session page. If they pass a `limits.context` value to `POST /api/sessions`, Cake rejects the request with `403 Forbidden`. ## Rules and validation * Limits are integers between 1 and 10,000,000 tokens. * If you set a context limit, you must also set an output limit. * A global limit must be defined before you can add per-model overrides. * Each model can have at most one override. An override can set context, output, or both; any value it omits falls back to the global limit. > [!WARNING] > > Setting a context limit that exceeds what a model can actually handle can result in unpredictable behavior. Check the model's documented context window before raising limits. ## API You can read and replace the organization's token limits programmatically: ```http theme={null} PUT /api/settings/token-limits Content-Type: application/json { "global": { "context": 200000, "output": 32000 }, "models": [ { "modelId": "anthropic/claude-sonnet-4-6", "context": 400000, "output": 64000 } ] } ``` `GET /api/settings/token-limits` returns the current setting in the same shape. `PUT` replaces the whole setting and returns `400` with a validation message if any value is invalid, a model ID is unknown, or a model appears twice. ## Related pages * [Configure Model Providers](/admin/model-providers) covers the provider and model definitions these limits apply to. * [Override token limits for a session](/user/session-token-limits) covers how users adjust limits for a single session. # Keep a warm session ready for faster session starts Source: https://docs.cake.ai/admin/warm-sessions Turn on the Keep a session warm setting so Cake Agents pre-provisions a spare session in the background and new sessions start faster. Starting a new session normally waits for Cake Agents to provision a data plane pod and for that pod to become ready. When you turn on **Keep a session warm**, Cake Agents keeps one spare session fully provisioned in the background. The next session someone creates takes over that spare instead of waiting for a new pod. The setting is off by default and applies to the whole organization. ## When to use a warm session * Your users start sessions often and notice the wait while a new session provisions. * Your cluster can afford one extra session pod running at all times. The spare consumes compute and storage even when nobody is using it. Leave the setting off if you want to minimize idle cluster resources. ## Prerequisites * You are signed in as an administrator. ## Turn on a warm session 1. Sign in to Cake Agents as an administrator. 2. Open `Settings → Organization → General`. 3. Toggle **Keep a session warm** on. The setting saves as soon as you select the toggle. Cake Agents checks the spare every minute, so the first spare may take a few minutes to become ready. To stop keeping a spare, toggle **Keep a session warm** off. ## How the warm session works * The spare is owned by an internal service account and is always private. It does not appear in anyone's session list. * When you create a session, Cake Agents assigns the ready spare to you with your title, model, privacy setting, and Slack thread, if any. * The spare's pod waits in a paused state until someone claims it. When you claim it, Cake Agents tells the paused pod to finish starting up with your configuration, such as your providers and instructions. The pod doesn't restart, so the session is usually ready to answer within seconds. * After a spare is claimed, Cake Agents provisions a new spare in the background for the next session. * If no spare is ready, for example because two sessions start at the same time, Cake Agents creates the session the usual way. # Core Concepts Source: https://docs.cake.ai/core-concepts Understand the control plane, data plane, and infrastructure boundaries in Cake Agents. 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. Treat the session namespace as fixed once sessions are running. The control plane only tracks session service accounts in the current `sessionNamespace`, so end or drain live sessions before you change it. ## Data Plane Authentication Each session pod runs under its own Kubernetes service account, named `session-`. Cake creates it when the session is provisioned and deletes it when the session ends. When a data plane pod calls the control plane, for example to fetch Git credentials or reach the Linear MCP server, it sends a short-lived service account token as a bearer token. The control plane accepts the request only when: * the token signature verifies against your cluster's published signing keys * the token is issued for the Cake Agents internal audience * the named service account still exists and matches the one Cake created for that session The token expires after 10 minutes and the kubelet rotates it automatically. Ending a session deletes its service account, so its token stops working right away. If the control plane cannot load the cluster's signing keys, it rejects internal requests instead of allowing them. ## 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. ```mermaid theme={null} flowchart LR U[Users] --> CP[Cake Agents Control Plane] CP --> DB[(PostgreSQL)] CP --> DP[Session Data Plane] DP --> OC[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. # Cake Agents Source: https://docs.cake.ai/index Deploy Cake Agents with Helm or Terraform and learn the platform architecture. Cake Agents runs a control plane in Kubernetes and launches per-session data plane pods for interactive agent work. Use these guides based on how you operate Cake Agents: * [Getting Started with the Console](./admin/getting-started-console) for existing Cake platform customers who sign up for the Cake Console and register a Kubernetes instance from it. * [Getting Started with Kubernetes](./admin/getting-started-kubernetes) for teams comfortable managing clusters and wanting a direct Helm install without the Console. * [Core Concepts](./core-concepts) for the platform model, architecture diagram, and component relationships. ## Admin Guides * [Set Up GitHub](./admin/github-setup) * [Configure Model Providers](./admin/model-providers) * [Configure the Small Model](./admin/small-model) ## User Guides * [Link GitHub](./user/link-github) * [Set Git Author Info](./user/set-git-author-info) * [Private sessions](./user/private-sessions) ## What You Deploy * A Cake Agents control plane web application * Session-scoped data plane pods launched on demand * PostgreSQL, either embedded for development or external for longer-lived environments * Kubernetes secrets for integrations such as Linear, LiteLLM, Slack, and auth ## Deployment Models * A direct Kubernetes and Helm install when you already operate a cluster * A fuller cloud environment provisioned with Terraform, including cluster, database, DNS, and the application release # Archive sessions Source: https://docs.cake.ai/user/archive-sessions Archive sessions you no longer need to free up cluster resources while keeping the session record and history, then restore them from S3 when you need them again. Archiving ends a session and releases its pod and persistent volume, but keeps the session record and its message history so you can find it later. Use archiving as the default cleanup path — reserve permanent deletion for sessions whose data must be removed. ## When to archive * You're done with a session and want to reclaim its cluster resources. * You want to tidy up your sidebar without losing the record of what happened. * You don't need the session right now, but you may want to reference the conversation or pick up the work later. If the session data must be permanently removed (for example, to satisfy a data retention policy), an admin can delete it instead. ## Who can archive * **You** can archive or restore any session you own. * **Admins** can archive, restore, or delete any session in the organization. Deleting a session is restricted to admins. ## Archive a session 1. In the sidebar, hover the session and open its menu (the three-dot icon). 2. Select **Archive**. 3. Confirm the action. The session moves to the **Archived** status. Its pod is stopped, its persistent volume is packaged into a compressed archive and uploaded to your organization's S3 bucket (when [S3 storage](/admin/aws-storage) is configured), and its messages are retained in the database. ## Automatic archiving Admins can configure Cake Agents to automatically archive sessions that have been idle for a set number of days. This keeps the sidebar tidy without anyone having to remember to clean up. * The sweep runs on a daily schedule. * Only sessions that have been inactive longer than the configured threshold are archived. * Cake Agents measures inactivity from the last time the agent finished a model response in the session. If the agent has never responded, Cake Agents measures from when the session was created. Pod restarts, deploys, and opening the session don't count as activity. * Starred sessions are always skipped. * Sessions already archived or deleted are skipped. ### Configure auto-archiving > [!NOTE] > > This is an organization-wide setting. Only admins can change it. 1. Go to **Settings → Organization → General**. 2. Toggle **Automatically archive inactive sessions** on. 3. Set **Archive sessions after** to the number of days of inactivity to allow (1–365). 4. Optionally, select **Archive now** to run the rule immediately instead of waiting for the daily sweep. You'll be asked to confirm before anything is archived. Turning the switch off (or setting the value to `0`) disables auto-archiving. ### Protect a session from auto-archiving Star a session to exclude it from automatic archiving. Starred sessions are never touched by the sweep, no matter how long they've been idle. Unstar the session when you're done, and it becomes eligible again on the next sweep. ## Find archived sessions Use the sidebar filter to show archived sessions: 1. Select the filter icon next to **Recent Sessions**. 2. Under **By Status**, select **Archived**. **By Status** supports multiple selections. Select **Live**, **Inactive**, or **Archived** to toggle each status on or off. The list shows sessions that match any selected status. For example, select both **Live** and **Archived** to see active and archived sessions together. Clear every status to show all sessions. ## What archiving preserves | Data | Archived | Deleted | | - | - | - | | Session record | Kept | Removed | | Message history | Kept | Removed | | Session data (files, git) | Archived to S3 | Removed | | Pod and persistent volume | Released | Released | Viewing archived messages inline is not yet available. ## Restore an archived session Restoring brings an archived session back to life with its files, git state, and conversation history intact. Cake Agents provisions a new pod and volume, and the pod unpacks the session's archive from S3 before the agent starts. The session keeps its original ID, so existing links still work. Restoring requires [S3 storage](/admin/aws-storage). The session must have been archived while S3 was configured. 1. Open the archived session, or find it in the sidebar with the **Archived** status filter. 2. Open the session menu (the three-dot icon). 3. Select **Restore**. The session moves to **Initializing**, then to **Live** once the agent is ready. The session timeline shows a **restored** event. If Cake Agents can't start the restore, it shows an error with the reason: | Message | What to do | | - | - | | This session is still being archived; try again shortly | The previous pod and volume are still being cleaned up. Wait a moment and select **Restore** again. | | This session has no archive to restore from | The session was archived without S3 configured, so its files weren't saved. You can't restore it. | | S3 must be configured to restore sessions | Ask an admin to configure [S3 storage](/admin/aws-storage). | Deleted sessions can't be restored. > [!NOTE] > > A restored session's volume starts at the configured [starting volume size](/admin/session-volume-autoscaling), not the size the volume had grown to before archiving. ## Storage requirements Archived session data is uploaded to S3-compatible object storage. If your deployment doesn't have S3 configured, archiving still ends the session and keeps the message history, but the session's files won't be preserved. See [S3 storage](/admin/aws-storage) to configure a bucket. # Compact sessions Source: https://docs.cake.ai/user/compact-sessions Summarize a long session and remove older messages from the database to free up context and keep working. Compacting a session replaces its older messages with a summary generated by the session's current model. Use it when a session has grown long enough that the model's context window is a limiting factor, or when you want to keep working in the same session without carrying every prior turn. ## When to compact * The session has been running long enough that responses are getting slower or hitting context limits. * You want to preserve the thread's history in place instead of starting a new session. * You're finished with an early phase of work (exploration, scaffolding) and want the summary to anchor the next phase. Compaction is destructive. Once older messages are summarized and removed from the database, you can't restore them. Start a fresh session instead if you might need the original turns later. ## Compact a session 1. Open the session. 2. In the session header, select **Compact**. 3. Select **Compact** to confirm. Compaction uses the session's current model. It doesn't change the model for later turns. The compaction runs in the background. When it finishes, a marker appears in the conversation showing who triggered it and when, and the session continues from the summary. Only the session owner and organization admins can compact a session. ## Automatic compaction Sessions can also be compacted automatically by the runtime when the context window fills up. Automatic compactions show up in the conversation the same way, labeled as `Compacted automatically` instead of attributed to a user. ## API You can trigger compaction programmatically. The request takes no body. ```http theme={null} PUT /api/sessions/{sessionId}/opencode/compact ``` * Returns `204 No Content` on success. * Returns `403 Forbidden` if you aren't the session owner or an admin. * Returns `409` while the session's OpenCode runtime is still provisioning, and `410` if the session is archived or deleted. # Change the conversation font size in Cake Agents Source: https://docs.cake.ai/user/conversation-size Make session conversations easier to read. Pick a font size from Extra-Small to Extra-Large without changing the rest of the Cake Agents web UI. Conversation size sets the font size of the session conversation view in the Cake Agents web UI. Use a smaller size to fit more of a long transcript on screen. Use a larger size if you find the default text hard to read. ## What conversation size changes Conversation size changes the text in two places: * Messages in the conversation, including agent replies, tool output, and session events. * The message box where you type prompts. The rest of the web UI keeps its normal size. That includes the sidebar, the session title bar, and the settings pages. ## Available sizes You can pick one of five sizes: * **Extra-Small** * **Small** * **Medium** (default) * **Large** * **Extra-Large** ## Change the conversation size 1. In the bottom-left, click your name → **User Settings**. 2. Open the **Interface** tab. 3. Set **Conversation Size** to the size you want. Each option shows a preview of that size. Your change saves automatically. Conversation size is a personal preference, so it only changes what you see. Other people in your organization keep their own sizes. ## Change the size with keyboard shortcuts While you view a session conversation, press Alt + Shift + = to increase the size one step. Press Alt + Shift + - to decrease it. Cake Agents saves the new size the same way as the **Conversation Size** setting. To rebind these shortcuts, see [Keyboard shortcuts](/user/keyboard-shortcuts). # Copy a session transcript Source: https://docs.cake.ai/user/copy-transcript Copy a plain-text transcript of a session from the session menu, or download the full session as a JSON file to share, archive, or debug. Copy a session's conversation as plain text when you want to share what happened, paste it into a ticket or doc, or hand it to another tool for review. The transcript captures who spoke, what each user and the agent said, and the tools the agent ran, without any UI chrome. ## Copy the transcript 1. Open the session. 2. Select the ⋯ icon to open the session menu. 3. Select **Copy Transcript**. The transcript is copied to your clipboard. Paste it wherever you need it. The **Copy Transcript** action is available whenever the session has loaded messages. If the session is still loading, wait for the message list to render before opening the menu. ## What the transcript includes Each turn is labeled with its source: * `# User :` for messages sent by a person, using their display name or email. * `# Agent:` for messages from the agent. * `# --- The session was automatically compacted ---` or `# --- User compacted the session ---` where a [compaction](/user/compact-sessions) happened. For each turn, the transcript preserves: * The text of the message. * Attached filenames, listed under **Attached files:**. * Tools the agent ran, summarized as `Ran tool: ` followed by the tool's inputs and outputs in a readable form. * Sub-agents the agent delegated to, listed under **Ran sub-agent:** with the sub-agent type and status. * Errors returned by the agent, rendered as a heading with the error message. Internal reasoning steps are omitted so the transcript reflects what a reader of the session would see. ## Download the session as JSON Download the raw session data when you need the full structured record instead of a readable summary. Use it for debugging or for processing the session with your own scripts. 1. Open the session. 2. Select the ⋯ icon to open the session menu. 3. Select **JSON**. Your browser downloads a `.json` file containing the session metadata and every message. The filename is based on the session title, such as `fix-login-bug.json`. If the title has no letters or digits, the session ID is used instead. ```json theme={null} { "session": { "id": "...", "title": "Fix login bug" }, "messages": [ ... ] } ``` # Set default repositories for new sessions Source: https://docs.cake.ai/user/default-repositories Save the GitHub repositories you work in most so Cake preselects them in the Working in picker every time you start a new session. Default repositories are the GitHub repos Cake preselects in the **Working in** picker on the **New session** screen. Save a default when you usually start sessions in the same repo or set of repos. You don't have to pick them again each time. Defaults are personal. Your saved defaults don't affect anyone else in your organization. ## Prerequisites * Your organization has the GitHub integration set up. See [GitHub setup](/admin/github-setup). ## Choose repositories for a session 1. Go to **New session**. 2. Open the **Working in** picker. 3. Search for a repo, then select it to add it to the session. Select it again to remove it. The picker shows the first selected repo, plus a `+n` badge when you've selected more than one. Hover the picker to see the full list. Select the × to clear every selected repo. ## Save a default 1. Open the **Working in** picker. 2. Hover a repo in the repo list and select **Make default**. The repo moves into the **Default** section at the top of the dropdown. Repeat for each repo you want preselected. You can save up to 20 default repos. After you create a session, Cake resets the picker to your saved defaults for the next one. ## Remove a default 1. Open the **Working in** picker. 2. Hover a repo in the **Default** section and select **Remove default**. When you remove your last default, the picker starts empty for new sessions. ## Know when your defaults are selected The picker shows a **Default** label next to the repo name when your selection exactly matches your saved defaults. If you add or remove a repo for a single session, the label disappears. Your saved defaults stay the same. When your selection exactly matches your defaults, the selection follows your default changes: * Selecting **Make default** on a repo also selects it for the current session. * Selecting **Remove default** on a repo also deselects it for the current session. # Set environment variables for Cake agent sessions Source: https://docs.cake.ai/user/environment-variables Add organization-wide or personal environment variables, such as API keys and tokens, that Cake injects into every session the agent runs. Environment variables give the agent and every command it runs access to values such as API keys, tokens, and service URLs. Use them when a tool, script, or test in your repo expects a value from the environment. Cake supports two scopes: * **Organization variables** apply to every session in your organization. Only users with the admin role can manage them. * **Personal variables** apply only to sessions you own. When both scopes define the same key, your personal value overrides the organization value in your sessions. ## Add a variable 1. Go to **Settings → User → Sessions** for a personal variable. For an organization variable, go to **Settings → Organization → Sessions**. 2. In the **Environment Variables** section, select **Add Variable**. 3. Enter a **Key** and a **Value**. 4. Toggle **Secret** on if the value is sensitive. 5. Select **Save**. Keys must start with a letter or underscore and contain only letters, digits, and underscores, up to 253 characters. Your personal **Sessions** page also lists organization variables. A personal variable with the same key replaces the organization one in that list. ## Override an organization variable Your personal **Sessions** page marks organization variables with a building icon. You can't edit or remove them there, but you can replace them with your own value in your sessions. * To set your own value, select **Create Override** (pencil icon) next to the organization variable. Cake opens the variable for editing with the key already filled in. Enter your value and select **Save**. * To set the variable to an empty string in your sessions, select **Create empty override** (eraser icon). Cake saves a personal variable with the same key and an empty value. To go back to the organization value, remove your personal variable. ## Import variables from a .env file 1. In the **Environment Variables** section, select **Import**. 2. Paste the contents of your `.env` file, then select **Import**. 3. Review the parsed keys and values. Remove any you don't want, and mark sensitive values as **Secret**. 4. Select **Save**. ```bash .env theme={null} DATABASE_URL=postgres://localhost:5432/app STRIPE_API_KEY=sk_test_123 ``` ## Secret variables Cake hides secret values once you save them. You can't view a secret value in the UI again, but you can replace it with a new value. Secret and non-secret variables reach the session the same way. Cake sends them to the session over an authenticated internal connection when the session container starts. Values aren't stored in the Kubernetes pod spec or in any volume that outlives the pod. ## When changes take effect Cake loads your variables each time a session container starts. New sessions get your current variables. A running session keeps the variables it started with until its container restarts. ## Reserved names Cake sets the following variables itself and ignores any variable you add with these names: * `CAKE_SERVICE_ACCOUNT_TOKEN_FILE` * `CAKE_AUTH_PROXY_PORT` * `CONTROL_PLANE_URL` * `SESSION_ID` * `CAKE_VOLUME_AUTOSCALING_ENABLED` # Watch CI and GitHub events from Cake sessions Source: https://docs.cake.ai/user/github-webhook-events Let Cake agents subscribe to GitHub webhook events so CI results and repository activity arrive in the session as messages the agent can act on. Cake agents can subscribe a session to GitHub webhook events for a repository. When a matching event arrives, Cake injects it into the session as a message, and the agent reacts to it. Use this when you want an agent to push a change, wait for CI, and fix failures without you checking back. ## Prerequisites * An admin has [set up the GitHub App](/admin/github-setup), and the App subscribes to the events the agent needs. * You have [linked your GitHub account](/user/link-github), and your account has access to the repository. ## Watch CI after a push Ask the agent to watch CI. For example: ```text theme={null} Push the fix to my branch, watch CI, and fix anything that fails. ``` Cake agents ship with a built-in `watch-ci` skill. With it, the agent: 1. Subscribes to `workflow_run` events for the repository before pushing, filtered to the branch or pull request it's watching. 2. Pushes the commits or opens the pull request. 3. Receives a message when each workflow run starts and completes. 4. Reports success, or fetches the failed logs with the `gh` CLI and fixes the failure. 5. Unsubscribes when it is done watching. If no event arrives, the agent falls back to polling CI status with `gh`. > [!NOTE] > > On deployments where an admin has [disabled public ingress](/admin/getting-started-kubernetes#optional-disable-public-ingress), GitHub can't deliver events to Cake. Agents can't create webhook subscriptions there, so the `watch-ci` skill polls CI with `gh` instead. ## Filter deliveries By default, a subscription delivers every matching event for the repository, including CI runs on other branches. Filters narrow a subscription to the deliveries you care about. A filter maps a dot-separated payload field path to a required exact value. The value can be a string, number, or boolean. Cake delivers an event only when every filter matches. If a payload field is an array, the filter matches when the array contains the value. If the field is missing from the payload, the event isn't delivered. Ask the agent to scope its subscription. For example: ```text theme={null} Watch CI on my-branch, but only tell me when runs complete. ``` The agent subscribes with filters like these: ```json theme={null} { "workflow_run.head_branch": "my-branch", "action": "completed" } ``` Common GitHub filters: | Filter | Delivers | | - | - | | `{"workflow_run.head_branch": "my-branch"}` | Workflow runs on one branch, including runs triggered by pull requests | | `{"action": "completed"}` | Only completed events, such as finished workflow runs | | `{"pull_request.number": 123}` | `pull_request` events for one pull request | A subscription accepts up to 16 filters. String values can't be empty. When the agent lists its subscriptions, each subscription shows its filters. ## Webhook messages in a session Webhook messages appear in the conversation marked as GitHub webhook deliveries, not as messages from a user. Each message includes the event name, action, repository, the agent's own reminder of what to do, and a truncated copy of the payload. The agent treats payload text as untrusted data, not as instructions. It uses the payload as a trigger and fetches authoritative state from GitHub. ## Subscription rules * Subscriptions are scoped to one session and one repository in `owner/repo` form. * Only events that happen after the agent subscribes are delivered. Cake doesn't replay past events. * Cake delivers events only while the session is live. * Cake checks repository access once, when the agent subscribes, using the GitHub account of the user who last messaged the session. If nobody has messaged the session yet, Cake uses the session creator's account. * The agent can subscribe only to the repository-level events below, and only if the GitHub App subscribes to them: | Category | Events | | - | - | | CI | `check_run`, `check_suite`, `workflow_job`, `workflow_run` | | Pull requests | `pull_request`, `pull_request_review`, `pull_request_review_comment`, `pull_request_review_thread` | | Code | `push`, `create`, `delete`, `commit_comment`, `release`, `fork` | | Repository | `repository`, `label`, `milestone`, `gollum`, `public`, `star`, `watch` | Subscriptions stay active until the agent removes them or the session ends. To stop deliveries, ask the agent to list and remove its webhook subscriptions. # Keyboard shortcuts Source: https://docs.cake.ai/user/keyboard-shortcuts Use and customize keyboard shortcuts to navigate the Cake Agents web UI faster. Keyboard shortcuts let you jump around the Cake Agents web UI without reaching for the mouse. A few shortcuts are built in, and nine are configurable per user. ## View all shortcuts Press Shift + / anywhere in the web UI to open the **Keyboard Shortcuts** modal. The modal lists every active shortcut, including any you have customized. You can also open it from the user menu in the bottom-left corner: click your name, then **Keyboard Shortcuts**. ## Built-in shortcuts These shortcuts are always available and cannot be changed. | Action | Shortcut | | - | - | | Open Spotlight (command palette) | Cmd / Ctrl + K, or / | | Open the Keyboard Shortcuts modal | Shift + / | ## Configurable shortcuts You can rebind these shortcuts. Most defaults use Alt instead of the meta key (Cmd / Ctrl) because meta combinations are usually reserved by the operating system or browser. **Toggle sidebar** uses Cmd / Ctrl + B to match VS Code and other editors. | Action | Default | Availability | | - | - | - | | New session | Alt + Shift + N | All users | | Next session | Alt + J | When the session sidebar is shown. Not on settings pages. | | Previous session | Alt + K | When the session sidebar is shown. Not on settings pages. | | Compact session | Alt + Shift + C | While viewing a session you can edit | | Increase conversation size | Alt + Shift + = | While viewing a session conversation | | Decrease conversation size | Alt + Shift + - | While viewing a session conversation | | Toggle sidebar | Cmd / Ctrl + B | Desktop layouts. Doesn't affect the mobile navigation menu. | | User settings | Alt + , | All users | | Organization settings | Alt + ; | Users with the admin role | ## Move between sessions **Next session** and **Previous session** step through the same list the sidebar shows. Starred sessions come first, followed by recent sessions. * The shortcuts include sessions beyond the visible part of the sidebar, so you can reach older sessions without scrolling. * The shortcuts use your current sidebar filters for user, visibility, and status. To navigate a different set of sessions, change the filters in the sidebar. * At the top of **Recent Sessions**, **Previous session** goes to the last starred session, if you have any. * Navigation stops at the first and last sessions. It doesn't wrap around. ## Change the conversation size **Increase conversation size** and **Decrease conversation size** change the conversation font size one step at a time, from **Extra-Small** to **Extra-Large**. At the smallest or largest size, the shortcut does nothing. Cake Agents saves the new size to your [conversation size](/user/conversation-size) setting. ## Change a shortcut 1. In the bottom-left, click your name → **User Settings**. 2. Open the **Interface** tab. 3. Under **Hotkeys**, click the shortcut you want to change and press the new key combination. Your change saves automatically and applies immediately. Clear a shortcut to disable that action. ## Notes * Some combinations may be intercepted by your operating system or browser and never reach Cake Agents. If a shortcut appears to do nothing, try a different combination. * Shortcut preferences are stored per user and apply anywhere you sign in to the same Cake Agents environment. # Link GitHub Source: https://docs.cake.ai/user/link-github Connect your GitHub account so Cake Agents can interact with GitHub on your behalf. Link your GitHub account so Cake Agents can interact with GitHub on your behalf. ## What This Enables After linking, Cake can use your GitHub identity within the permissions granted by the application and the GitHub App. This is what enables workflows such as: * opening pull requests * pushing commits * working with GitHub-backed repos and actions in sessions ## Link Flow 1. In the top right of Cake Agents, click your name → "User settings". 2. Open the **Git** tab, then under **GitHub** click "Link GitHub Account". Optionally you can override the default author identity for git commits, see [Set Git Author Info](./set-git-author-info). ## Troubleshooting * If GitHub linking is unavailable, your administrator may not have finished the environment GitHub setup. * If Cake cannot push or open PRs for you, reconnect GitHub. * If your GitHub link stops working later, refresh or reconnect it from settings. # Connect your account to MCP servers Source: https://docs.cake.ai/user/mcp-connectors Connect your own account to the MCP servers your organization enabled so Cake agents can call their tools on your behalf in your sessions. Your organization's admins choose which MCP (Model Context Protocol) servers are available in Cake Agents. Before an agent can use a server's tools in your sessions, you connect your own account to it. The agent then acts with your permissions on that service. ## Prerequisites * An admin has added at least one MCP server. See [Add MCP servers for your organization](/admin/mcp-servers). * You have an account with the service behind the MCP server. ## Connect a server 1. Open **User settings → MCP Connectors**. 2. Find the server and select **Connect**. 3. Sign in to the service and approve access. The service redirects you back to **MCP Connectors**, and Cake shows a notification with the result. The server now shows a **Connected** badge. Cake notifies your running sessions, so the agent can use the server's tools without you starting a new session. If the page shows **No servers yet**, your organization hasn't added any MCP servers. ## Use connected servers in sessions When you message a session, the agent can call tools from every server you've connected. Each tool name is prefixed with the server name that the admin chose, for example `Notion.search`. Ask the agent to use the service directly: ```text theme={null} Search Notion for the Q3 launch plan and summarize the open risks. ``` ### Check which servers you've connected The agent can list every MCP server your organization added and whether you've connected each one. Ask it directly: ```text theme={null} Which MCP servers am I connected to? ``` The agent also checks your connection status on its own when a task seems to need a server whose tools aren't available. If a server isn't connected, the agent can suggest that you connect it in **User settings → MCP Connectors**. In shared sessions, the status reflects the connections of the last person who sent a message. ## Shared sessions When more than one person sends messages in a session, the agent uses the MCP connections of the last person who sent a message. When you send a message, the agent's next MCP tool calls use your connections and act with your permissions. Anyone who can message the session counts, including teammates who message a public session. Servers that the last person hasn't connected don't contribute any tools. When a different person sends a message, Cake updates the session's list of available tools to match that person's connections. Until someone sends a message, the agent uses the connections of the person who created the session. Messages that Cake adds on its own, such as [GitHub webhook deliveries](/user/github-webhook-events), don't change whose connections the agent uses. If Cake can't determine the last user, for example because the session or user no longer exists, the tool call returns: ```text theme={null} The MCP server "Notion" is not available: the last user of this session could not be determined. Try the call again. ``` Ask the agent to retry the call. ## Missing or expired connections If a connection is missing or has expired, the tool call returns a message such as: ```text theme={null} The MCP server "Notion" is not connected. Connect it in your MCP Connectors settings to use its tools. ``` Open **User settings → MCP Connectors** and connect or reconnect the server, then ask the agent to try again. ## Get a connection link from the agent Sometimes a task involves a service the agent has no tools for. For example, you might share a link to a page that only loads after you sign in. In that case, the agent checks which MCP servers your organization has registered and which ones you've connected. It then replies based on what it finds: | Situation | What the agent gives you | | - | - | | The server is registered, but you haven't connected it | A link that starts the sign-in flow for that server. Open it, sign in to the service, and approve access. | | The server isn't registered in your organization | A registration link to pass to an admin. Only admins can add servers. See [Register a server from an agent link](/admin/mcp-servers#register-a-server-from-an-agent-link). | | You've connected the server, but the agent still has no tools for it | A suggestion to disconnect the server in **User settings → MCP Connectors** and connect it again. | After you connect, tell the agent. It checks your connections again before it continues the task. You can also ask the agent directly: ```text theme={null} Which integrations can you use, and which ones am I connected to? ``` ## Disconnect a server 1. Open **User settings → MCP Connectors**. 2. Select **Disconnect** next to the server. Cake removes the server's tools from your running sessions. Agents can no longer call that server's tools with your account until you connect again. # Private sessions Source: https://docs.cake.ai/user/private-sessions Keep sessions visible only to you, and set defaults for the web UI, Slack threads, and Slack agent DMs. Private sessions are visible only to their owner. Public sessions remain visible to everyone in your organization. Use private sessions when you're exploring sensitive code paths, drafting work you don't want to share yet, or experimenting in a personal scratch space. ## When to use private sessions * You're working on something that isn't ready for teammates to see. * The session involves sensitive repositories, credentials, or customer data. * You want a personal scratch space without cluttering the shared sidebar. For collaborative work (code reviews, pair sessions, anything you want teammates to jump into), leave the session public. ## Create a private session ### From the web UI 1. Go to **New session**. 2. Toggle **Private** before submitting. 3. Create the session. A lock icon next to the session title indicates it's private; a globe icon indicates it's public. ### From Slack New Slack threads and Slack agent direct messages can have different default visibility. When a Slack conversation starts a new Cake session, it uses the default for that conversation type. You can also set visibility through the API when creating a session: ```http theme={null} POST /api/sessions Content-Type: application/json { "title": "Investigate auth flow", "private": true, "initialUserPrompt": "Walk me through the login handshake" } ``` The `private` field is required on session creation. Set it to `true` for a private session or `false` for a public one. ## Filter sessions in the sidebar The sidebar can show public sessions, private sessions, or both. * Select the filter icon next to **Recent Sessions**, then under **Visibility** choose **All**, **Private**, or **Public**. * Private sessions you do not own never appear in the list. ## Set default visibility You can configure the default visibility for new sessions in **Settings → User → Sessions → Privacy**. Three defaults are available: | Setting | Applies to | Default | | - | - | - | | Web UI | Sessions started from the **New session** screen | Public | | New Slack threads | Sessions started by mentioning the bot or replying in Slack | Public | | Slack agent DMs | Sessions started from the Chat tab in the Slack app | Private | Each setting has two scopes: * **Organization default** (set by an admin and applied to everyone who hasn't overridden it). * **User override** (your personal preference, which takes precedence over the org default). Toggle the switch to flip between public and private. Use the remove control next to a setting to clear your user override and fall back to the organization default. > [!TIP] > > Slack agent DMs default to private because direct messages are already a one-on-one space. You can change this if your team prefers shared visibility. ## How visibility is enforced * Private sessions are filtered out of session list endpoints for users who don't own them. * The session events stream (`GET /api/sessions/events`) skips private sessions whose owner isn't the subscriber. * Session detail, message, and action routes return a not-found response for private sessions that don't belong to the requester. Changing a session's owner or visibility after creation isn't supported. Pick the visibility that fits when you start the session. # Rename sessions Source: https://docs.cake.ai/user/rename-sessions Rename a Cake session from the sidebar, the session header, or by asking the agent, and see every rename recorded in the conversation timeline. Every session starts with an auto-generated title. Rename it whenever the default doesn't reflect the work you're actually doing. A good title makes sessions easier to find in the sidebar and easier for teammates to recognize. ## Who can rename a session * The user who created the session. * Any user with the **admin** role. Everyone else sees the title as read-only. ## Rename from the session header 1. Open the session. 2. Select the pencil icon next to the title. 3. Edit the title inline. Press **Enter** to save or **Escape** to cancel. ## Rename from the sidebar 1. Hover the session in the sidebar and open its menu (the ⋯ icon). 2. Select **Rename**. 3. Enter a new title in the modal and confirm. ## Title rules * Titles must be between 1 and 50 characters. * Leading and trailing whitespace is trimmed. * Once you set a custom title, Cake stops overwriting it with auto-generated titles. * The agent can still replace a custom title if it renames the session on purpose. See [Let the agent rename the session](#let-the-agent-rename-the-session). ## Let the agent rename the session The agent can name its own session with the `cake_set_session_title` tool from the Cake MCP server. Use this when you want the title to describe the work as it takes shape, or ask the agent directly: ```text theme={null} Rename this session to "Fix flaky login tests". ``` Agent renames work differently from user renames: * The tool only renames the session the agent is running in. * The agent's title replaces the current title, including a custom title you set. * Agent titles can be up to 255 characters. Cake trims leading and trailing whitespace and rejects blank titles. * The timeline shows the event as "Session title was automatically changed to …", with no user attribution. * An agent rename doesn't count as user activity on the session. ## Rename events in the conversation Every rename is recorded as an event in the conversation timeline, showing the previous title, the new title, and who made the change. This makes it easy to see how a session's focus evolved and who reframed it. Rename events also stream to anyone viewing the session, so titles update live in the sidebar and header without a refresh. ## Rename through the API You can also rename a session with a `PATCH` to the session endpoint: ```http theme={null} PATCH /api/sessions/{sessionId} Content-Type: application/json { "title": "Investigate auth flow" } ``` The same permission rules apply: the caller must own the session or hold the admin role. A successful rename returns `204 No Content`; sending the current title returns `400 No changes made`; a caller without permission gets `403 Forbidden`. # Guide agents with AGENTS.md repository instructions Source: https://docs.cake.ai/user/repository-instructions Add an AGENTS.md file to your repository so Cake agents follow your project's conventions, build commands, and lint and test steps in every session. Repository instructions are files in your repository that tell coding agents how to work in your project. Before a Cake agent works in a repository, it looks for these files, reads them, and follows them. Add repository instructions when you want every session to use the same conventions and commands. You don't have to repeat them in each prompt. ## Supported files The agent looks for any of these files: * `AGENTS.md` at the repository root * `AGENTS.md` in the subdirectories the agent works in * `CLAUDE.md` * `GEMINI.md` * `.github/copilot-instructions.md` If your repository already has instructions for another coding tool, Cake agents use them too. ## How agents use instructions * The agent reads the instructions for every repository it works in. This includes repositories it clones or checks out during the session. * The guidelines, conventions, and commands in your instructions take precedence over the agent's default guidance. * When the agent can't find a lint or typecheck command, it asks you for one. It may then suggest adding that command to `AGENTS.md` so future sessions run it automatically. ## Write an AGENTS.md file 1. Create `AGENTS.md` at the root of your repository. 2. Add the conventions and commands you want agents to follow. 3. Commit the file to the branch your sessions use. ```markdown AGENTS.md theme={null} # Agent instructions ## Commands - Install dependencies: `pnpm install` - Lint: `pnpm lint` - Typecheck: `pnpm typecheck` - Test: `pnpm test` ## Conventions - Use TypeScript for all new code. - Run lint, typecheck, and tests before you commit. - Don't edit generated files in `dist/`. ``` To give instructions that apply to one part of a monorepo, add another `AGENTS.md` in that subdirectory. ## Related pages * [Set default repositories for new sessions](/user/default-repositories) # Read session status indicators in the Cake Agents sidebar Source: https://docs.cake.ai/user/session-status Learn what the session owner's dot in the sidebar means, so you can tell at a glance which agents are working, waiting for input, errored, or archived. Each session in the sidebar starts with a dot in the session owner's color. The dot also shows the session's status. Use it to see which agents are still working and which ones are waiting for you, without opening each session. ## Status indicators | Indicator | Status | What it means | | - | - | - | | Solid dot in the owner's color | **Live** | The agent is working on a response. | | Solid dot in the owner's color | **Initializing** | Cake is starting the session's pod. | | Hollow dot outlined in the owner's color | **Idle** | The pod is running and the agent is waiting for your input. | | Solid dot inside a yellow square frame | **Error** | The session's pod failed. | | Muted gray dot | **Archived**, **Ending**, **Missing**, or **Deleted** | The session is no longer running. | Hover the dot to see who owns the session. Screen readers announce the status as **Session status: \**. The indicator updates live. When an agent finishes a turn, its dot changes from solid to hollow. That's your cue to review the result or send the next message. > [!TIP] > > To list only sessions with a given status, use the **By Status** filter in the sidebar. See [Archive sessions](/user/archive-sessions#find-archived-sessions). # Override token limits for a session Source: https://docs.cake.ai/user/session-token-limits Set a custom context and output token limit for a single session when you create it, instead of using your organization's defaults. Your organization's administrators can set default context and output token limits that apply to every session. When you create a session, you can override those defaults for that session only. > [!NOTE] > > Admins can always override session limits. If you aren't an admin, you can only override them when an administrator turns on **Allow non-admin overrides** in the organization's [token limits settings](/admin/token-limits#allow-non-admin-overrides). Otherwise the token limits control doesn't appear. Use an override when one session needs a different budget than usual. For example, a large refactor may need more context, or a quick fix may not need the full default window. ## Set limits for a new session You can only set session limits when you create the session. After the initial prompt, the session keeps the limits it started with. 1. Open the New Session page. 2. In the message composer, select the token limits button (coins icon). Its tooltip reads `Default Token Limits` when no override is set and `Custom Token Limits` when one is. 3. In the `Adjust Session Token Limits` dialog, enter a `Context Limit`, an `Output Limit`, or both. Each field's placeholder shows the default that applies to the selected model. 4. Select **Save**. To go back to your organization's defaults, reopen the dialog and reset the values. If the selected model has a maximum context size configured by your administrators, the dialog shows it and caps your input at that value. > [!WARNING] > > Setting a limit above the model's actual maximum may result in unexpected behavior. ## API You can set limits when creating a session programmatically by passing the optional `limits` object: ```http theme={null} POST /api/sessions Content-Type: application/json { "title": "Refactor payment service", "private": false, "model": "anthropic/claude-sonnet-4-6", "limits": { "context": 400000, "output": 64000 } } ``` Both `context` and `output` accept integers between 1 and 10,000,000. Omit the `limits` object to use your organization's defaults. If you aren't an admin and non-admin overrides are off, a request that sets `limits.context` returns `403 Forbidden`. # Set Git Author Info Source: https://docs.cake.ai/user/set-git-author-info Configure the git author name and email used for commits made in Cake sessions. Git author info controls the name and email written into commits created inside sessions. GitHub linking and git author identity are not the same thing. Git commit identity is also not the same thing as GitHub push permission. Your commit name and email control how commits are authored. Your linked GitHub account controls whether Cake can interact with GitHub on your behalf. ## What to Set Set these values in your user settings: * git author name * git author email Use the identity you want attached to commits created by Cake on your behalf. ## Recommended Setup * Set your git author name to your preferred commit display name. * Set your git author email to the email you want on commits. * Prefer using the same email address that is registered with your GitHub account. * Make sure the values match your expected commit identity. ## Troubleshooting * If commits show the wrong author name or email, update your git author settings. * If Git operations work but the commit identity is wrong, this is usually a git author settings issue rather than a GitHub linking issue. For account linking, see [Link GitHub](./link-github). # Slack thread verbosity Source: https://docs.cake.ai/user/slack-verbosity Choose whether Cake streams live updates to Slack or posts only the final agent reply once the session is idle. Slack thread verbosity controls how much of an agent's work Cake publishes back into a Slack thread. Use it to keep noisy sessions from cluttering Slack, or to keep the default streaming experience for teammates who want to watch progress in real time. ## Verbosity levels | Level | What Cake posts to Slack | | - | - | | **Normal** | Streaming updates as the agent works, including intermediate text parts and sub-agent activity. | | **Low** | Nothing until the session transitions to idle, then only the last agent message that contains text. | Low verbosity is a good fit when: * You want a clean Slack thread that shows only the final answer. * You're running longer sessions where streaming intermediate updates is more noise than signal. * You prefer to follow detailed progress in the web UI and use Slack for the summary. Leave verbosity on Normal when you want teammates to see the agent's reasoning as it happens. > [!NOTE] > > Low verbosity is a "wait and dump" implementation. Cake does not stream tokens to Slack in this mode; the final message appears all at once when the session finishes. ## Configure verbosity Verbosity has two scopes: * **Organization default** — set by an admin and applied to everyone who hasn't overridden it. * **User override** — your personal preference, which takes precedence over the org default. ### Set your personal verbosity 1. Go to **Settings → User → Slack**. 2. Under **Slack Settings**, set **Thread Verbosity** to **Normal** or **Low**. 3. Clear the field to remove your override and fall back to the organization default. Changes save automatically. ### Set the organization default Admins can set the default for everyone in the workspace: 1. Go to **Settings → Organization → Integrations**. 2. Next to **Slack**, select **Connected**. 3. Under **Slack Settings**, set **Thread Verbosity** to **Normal** or **Low**. Users who haven't set their own verbosity inherit this value. ## Scope Verbosity applies to Slack threads only. It does not change what you see in the web UI, and it cannot be configured per-model or per-session. The setting is evaluated per Slack event using the session owner's preference, so different users in the same channel can see different behavior based on who started the session.