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.

npm run doctor checks that your machine is ready to run Cake Agents locally. Use it whenever a npm run dev command fails with a missing binary, an unexpected Node version, or an unset environment variable.

​
When to use it

  • Before your first npm run dev on a new machine.
  • After pulling changes that bump .node-version or add new tooling.
  • When a dev command reports a missing executable on PATH.
  • When the server exits before listening (often a missing DATABASE_URL).

​
Run it

From the repository root: 
npm run doctor
The script exits non-zero if any required binary is missing.

​
What it checks

The output is grouped into sections.

​
Binaries

CheckRequiredNotes
nodeyesInstall Node or use nix develop.
npmyesBundled with Node.
direnvyesAfter install, run direnv allow.
nixrecommendedProvides the flake dev shell.
kubectlfor default flowRequired for AWS/K8s dev.
ktunnelfor default flowRequired for AWS/K8s dev.
dockeroptionalSome tests and image builds.
helmoptionalRequired for Helm deploy workflows.

​
Repo

  • node-version — Compares the installed Node version against .node-version. A mismatch prints a warn line; the dev shell pins the expected version.
  • .envrc — Confirms the file is present (expected for the default dev flow).

​
Environment

  • direnv — Confirms direnv is loaded in the current shell. If not, run direnv allow and re-open the shell.
  • DATABASE_URL — Must be set. The server will not start without it.
  • DATA_PLANE_IMAGE / DATA_PLANE_INIT_IMAGE — Should both be set. The dev:local script sets dummy defaults for the sandboxed fallback.

​
Example output

Binaries
ok   node         /usr/local/bin/node
ok   npm          /usr/local/bin/npm
ok   direnv       /usr/local/bin/direnv
miss kubectl      Required for the default dev flow (AWS/K8s)

Repo
ok   node-version  22.11.0
ok   .envrc         present

Environment
ok   direnv         loaded
warn DATABASE_URL   unset (server will not start without it)
warn data-plane     DATA_PLANE_IMAGE/DATA_PLANE_INIT_IMAGE unset (dev:local sets dummy defaults)

Next Commands
1. Default dev (AWS/K8s): direnv allow && npm run dev
2. Local fallback (no AWS/K8s): cd packages/web && DATABASE_URL=... npm run dev:local
A line that starts with ok is healthy, warn is informational, and miss indicates a missing required binary that will block local development.