Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cake.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets a local Cake Agents development environment running. The default and preferred path is the full AWS/Kubernetes-backed flow. A sandboxed fallback exists for environments without cluster access.

​
Prerequisites

Install these tools before you start. Run npm run doctor at any point to verify your setup.
  • Node — version pinned in .node-version
  • npm — bundled with Node
  • direnv — loads .envrc automatically
  • Nix (recommended) — provides the flake dev shell
  • kubectl and ktunnel — required for the default AWS/K8s flow
  • Docker — needed for some tests and image builds
  • Helm — needed for the Helm deploy workflow

​
Default flow (AWS/Kubernetes)

This flow loads environment variables from .envrc, brings up a Postgres connection, and connects to the dev Kubernetes cluster used by real session data planes.
1

Allow direnv

From the repository root, trust the .envrc:
direnv allow
2

Start the dev server

npm run dev
If your shell does not auto-load direnv, run the command through direnv explicitly:
direnv exec . npm run dev
3

Open the UI

The web app listens on http://localhost:4000.
OpenCode runs inside each session’s data plane pod on port 4096. Locally, the server uses per-session kubectl port-forward to reach pods — no shared OpenCode service proxy is required.

​
Sandboxed fallback (no AWS/K8s)

Use this mode only when AWS or Kubernetes access is unavailable — for example, no SSO, no cluster credentials, or no kubectl / ktunnel. Data plane behavior is not representative of normal local development. 
cd packages/web
DATABASE_URL=postgres://postgres@localhost:5432/cake_agents npm run dev:local
The Vite client (port 4000) proxies /api to the backend (port 4001).

​
Required environment variables

VariableDescription
DATABASE_URLPostgreSQL connection string. The server will not start without it.
DATA_PLANE_IMAGEContainer image used for session data plane pods. dev:local sets a dummy default.
DATA_PLANE_INIT_IMAGEInit container image for data plane pods. dev:local sets a dummy default.
Optional variables:
VariableDefaultDescription
PORT4000Server port
NODE_ENVdevelopmentEnvironment mode
KUBE_CONTEXTin-clusterKubernetes context name
SESSION_NAMESPACEopencode-sessionsNamespace for session workloads

​
Quality checks and tests

From packages/web: 
npm run check   # oxlint, oxfmt, stylelint, typecheck in parallel
npm test        # auto-starts a local Postgres if TEST_DATABASE_URL is unset
Filter tests by tag: 
npm test -- --tags-filter="!db & !k8s"   # fast unit-ish runs
npm test -- --tags-filter="db"            # database tests
npm test -- --tags-filter="k8s"           # Kubernetes tests

​
Troubleshooting

  • Missing executables — Load the Nix flake dev shell with nix develop --command <command>, or trust direnv with direnv allow.
  • initdb / pg_ctl not found — Run them through the flake: nix develop --command initdb -D ~/.local/state/cake-agents/pgdata --no-locale --encoding=UTF8 -A trust -U postgres.
  • Postgres pod crash loops — The official Postgres 18 image expects the PVC mounted at /var/lib/postgresql. For disposable dev data, delete the release’s Postgres PVC once so a fresh data directory is created.