kody Setup

August 29, 2026 · View on GitHub

Use these steps to run kody locally and on Cloudflare Workers.

If you are here to understand the purpose of this repository rather than set it up, read docs/contributing/project-intent.md first. Some docs and parts of the repo structure reflect starter-oriented conventions, and the project intent is to build a personal assistant with an MCP-first architecture.

Install dependencies

We use npm for installs and scripts, with Node 26 as the runtime.

npm install

To scaffold a new project from the epicflare template instead of working inside this repo, run npx create-epicflare.

Expectations and assumptions

The setup flow assumes:

  • Node 26 and npm are installed.
  • You run commands from the repo root (needs nx.json, package.json, and packages/worker/wrangler.jsonc).
  • Cloudflare D1 and KV: The checked-in packages/worker/wrangler.jsonc declares bindings and database_name values but does not commit remote resource IDs (database_id, KV id / preview_id). Production and preview deploys run ensure scripts that create or resolve resources and write generated Wrangler configs with real IDs (see docs/contributing/setup/local-development.md). Local development does not require provisioning remote D1 or KV; npm run dev uses local Wrangler persistence.

See docs/contributing/setup-manifest.md for required resources and secrets.

For optional Cloudflare offerings (R2, Workers AI, AI Gateway, extra KV), see docs/contributing/cloudflare-offerings.md.

Preflight checks

Verify Node 26 and that dependencies are installed:

node --version   # expect v26.x
npm install

For deploy work, confirm Wrangler can reach your Cloudflare account:

npx wrangler whoami

Quick Start (local only)

  1. Copy the local environment file and adjust secrets if needed:
cp packages/worker/.env.example packages/worker/.env

COOKIE_SECRET and SECRET_STORE_KEY are required. The example file includes placeholder values that work for local development.

  1. Apply local D1 migrations:
npm run migrate:local
  1. Start local development:
npm run dev:ensure

That reuses a healthy origin if one is already up, otherwise starts npm run dev. Either way it prints the resolved URL (default port 3742) once /health is ok. For an interactive session, run npm run dev instead. Health check:

curl http://localhost:<port>/health

Full Cloudflare setup (deploy)

Local setup does not create Cloudflare resources. The checked-in Wrangler template omits remote D1/KV IDs on purpose. The production deploy workflow runs node tools/ci/production-resources.ts ensure, which creates missing D1/KV resources when needed and writes packages/worker/wrangler-production.generated.json with resolved IDs for that deploy. Cloudflare deploys do not auto-create those resources from bindings alone, so the workflow runs that ensure step before migrations/deploy.

  1. Configure GitHub Actions secrets and variables for deploy:
  • CLOUDFLARE_API_TOKEN (Workers deploy + D1 edit + Workers KV Storage:Edit access on the correct account)
  • COOKIE_SECRET (generate with openssl rand -hex 32 or similar)
  • See docs/contributing/setup-manifest.md (GitHub Actions configuration) for full optional secrets/variables and where to get each value.
  1. Deploy production through GitHub Actions (.github/workflows/deploy.yml). That workflow uploads kody-platform, kody-runtime, kody-jobs, and origin in the order documented in architecture. npm run deploy from a laptop uploads the origin script only (packages/worker); it is not a full production ship.

Agent/CI setup

For non-interactive or automated setup:

  1. Ensure packages/worker/.env exists (copy from .env.example if missing).
  2. Run migrations and the full validation gate:
npm run migrate:local
npm run validate

npm run validate is the single authoritative local gate. It runs format, lint, typecheck, unit tests, Playwright E2E, MCP E2E, backup/status/nx-cache/jobs/ runtime/platform dry-run builds, and structure checks in parallel. CI runs the same checks as parallel jobs (node and workers unit suites on separate runners).

To seed a deterministic test login after migrations:

node tools/seed-test-data.ts --local

Cloudflare resources are managed during deploy. Deploy-time ensure steps inject real D1/KV IDs into generated Wrangler configs (not into the checked-in template).

Local development

See docs/contributing/setup/local-development.md for local dev commands and docs/contributing/setup/checks.md for verification steps.

To create a deterministic test login after migrations, see docs/contributing/setup/seeding.md.

Build and deploy

Build the project:

npm run build

Deploy the origin script to Cloudflare (not the full four-script production fleet — see architecture):

npm run deploy