# 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://<bucket>/<prefix><session-id>.tar.gz
```

Message history is stored in the database, not in S3.


# 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

<img alt="Cake Agents Architecture" />

Cake Agents has two runtime layers:

* The control plane is a web application deployed as a standard Kubernetes workload.
* Each user session launches a data plane pod that runs OpenCode inside the cluster.

The chart also manages supporting pieces such as RBAC, optional embedded PostgreSQL, optional Istio resources, and integration secrets.

## Prerequisites

* A working Kubernetes cluster
* `kubectl` configured for the target cluster
* `helm` 3+
* A DNS name for the control plane
* An ingress controller or API gateway configured to route traffic to the control plane (e.g. Istio, Nginx, ALB, etc.)
* Kubernetes secrets or secret-management flow for integration credentials
* Optionally, a preexisting Postgres database

## What the Helm Chart Configures

The Helm install configures these main concerns:

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

## Set up DNS

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

## Choose a Database Strategy

For development, the chart defaults to embedded PostgreSQL.

For shared or production-like environments, use an external database and provide a secret instead:

```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 or Public (with PKCE)
* Redirect URI: `https://<controlPlane.host>/api/auth/callback/oidc`
* Scopes: `openid email profile`

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

```yaml theme={null}
kind: Secret
apiVersion: v1
metadata:
  name: sso-oidc
  namespace: cake-agents
type: Opaque
stringData:
  clientSecret: <your-client-secret>
```

## Minimal Values File

Start from a small values file and expand from there:

```yaml theme={null}
image:
  tag: 0.5.0

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

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

oidc:
  enabled: true

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

postgresql:
  enabled: false
```

## Install with Helm

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

```bash theme={null}
aws ecr get-login-password --region us-east-2 | helm registry login --username AWS --password-stdin 684117700585.dkr.ecr.us-east-2.amazonaws.com
```

Then you can install the chart with your values file:

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

Once you're installed, you'll need to configure your ingress or gateway to route traffic to the control plane service. If using Istio, you can enable the built-in gateway configuration in the chart and point your DNS at the gateway's external IP.

After you can reach the control plane in the browser, you're ready to set up integrations:

* [GitHub setup](./github-setup)
* [Model provider setup](./model-providers)

## 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.

## Values Reference

```yaml theme={null}
registry:
  # Shared fallback registry used when controlPlane/dataPlane/dataPlaneInit image registry is empty.
  default: 684117700585.dkr.ecr.us-east-2.amazonaws.com

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

controlPlane:
  # Note: control plane is not yet designed for multi-replica operation
  # and should be deployed with replicaCount: 1 for now.
  replicaCount: 1
  image:
    registry: ""
    repository: cake-agents/web
    tag: latest
    pullPolicy: Always
  imagePullSecrets: []
  # Public host used by Istio ingress resources and default ALLOWED_HOSTS.
  host: ""
  # Additional entries appended to ALLOWED_HOSTS (Vite-style: leading `.` = suffix).
  extraHosts: []
  deployment:
    # Set to override data plane image entirely (e.g. CI tag)
    dataPlaneImage: ""
    # Set to override data plane init image entirely (e.g. CI tag)
    dataPlaneInitImage: ""
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
    livenessProbe:
      path: /api/health
      periodSeconds: 30
      failureThreshold: 3
    readinessProbe:
      path: /api/health
      periodSeconds: 10
      failureThreshold: 3
    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:
  storageSize: 2Gi
  # Empty = use cluster default StorageClass
  storageClassName: ""

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

# Data plane images
dataPlane:
  image:
    registry: ""
    repository: cake-agents/data-plane
    tag: main

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

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

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

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

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

# If using Istio, the chart can optionally configure an Istio Gateway and VirtualService to route traffic to the control plane. You can also export the gateway credential for use in external DNS and TLS configuration.
istio:
  enabled: false
  inject: true
  gateway:
    name: ""
    create: false
    # Istio
    credentialName: istio-gateway-certificate-tls
```


# 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 → GitHub`.
2. Enter the name your GitHub organization. We will use this to create a GitHub App for your organization's instance of Cake Agents.
3. Click "Continue to GitHub".
4. For "GitHub App name" append your company name. For example "Cake Agents - ACME Corp".
5. Click "Create GitHub App for \<your org>

## Install the GitHub App

1. Back in Cake Agents, navigate to "Settings → Organization → GitHub".
2. Click "Continue to GitHub".
3. Select the repositories you'd like to enable (this can be changed later), then click "Install".

## 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.


# 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.


# 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.


# 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.

## 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 infrastructure:

* [Getting Started with Kubernetes](./admin/getting-started-kubernetes) for teams comfortable managing clusters and wanting a direct Helm install.
* [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 preserving the session record and message history.

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'll never restart the session, but you may still want to reference the conversation.

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 any session you own.
* **Admins** can archive 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.
* 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.</Note>

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 at the top of the session list.
2. Under **By Status**, select **Archived**.

You can also filter by **Live**, **Inactive**, or **All** to focus on active work.

## 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 |

Restoring an archived session and viewing archived messages inline are not yet available.

## 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 a model you pick. 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. Pick the model that should generate the summary. The session's current model is selected by default.
4. Select **Compact** to confirm.

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:

```http theme={null}
PUT /api/sessions/{sessionId}/opencode/compact
Content-Type: application/json

{
  "modelId": "anthropic/claude-sonnet-4-5"
}
```

* `modelId` is required and must be a valid `providerId/modelId` pair for a provider configured in your deployment. See [Model providers](/admin/model-providers) for how models are registered.
* Returns `204 No Content` on success.
* Returns `400 Invalid model ID` if the model isn't recognized.
* 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.


# 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 four are configurable per user.

## View all shortcuts

Press <kbd>Shift</kbd> + <kbd>/</kbd> 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)  | <kbd>Cmd</kbd> / <kbd>Ctrl</kbd> + <kbd>K</kbd>, or <kbd>/</kbd> |
| Open the Keyboard Shortcuts modal | <kbd>Shift</kbd> + <kbd>/</kbd>                                  |

## Configurable shortcuts

You can rebind these shortcuts. Defaults use <kbd>Alt</kbd> instead of the meta key (<kbd>Cmd</kbd> / <kbd>Ctrl</kbd>) because meta combinations are usually reserved by the operating system or browser.

| Action                | Default                                          | Availability                         |
| --------------------- | ------------------------------------------------ | ------------------------------------ |
| New session           | <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>N</kbd> | All users                            |
| Compact session       | <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> | While viewing a session you can edit |
| User settings         | <kbd>Alt</kbd> + <kbd>,</kbd>                    | All users                            |
| Organization settings | <kbd>Alt</kbd> + <kbd>;</kbd>                    | Users with the admin role            |

## 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.


# 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.

* Use the visibility filter (globe and lock icons) at the top of the session list to toggle which sessions are displayed.
* 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.
</Tip>

## 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

Give a session a clearer title from the sidebar or the session header, and see rename events 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 from the agent.

## 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`.


# 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.
</Note>

## 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 → Slack**.
2. 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.