Skip to content
Mnemose

6. Local development

Run the full Mnemose stack on your workstation against local Cloudflare state — D1 (SQLite) via wrangler dev/workerd. No cloud account required for the core loop; no Docker, Postgres, or emulators participate anymore.

For deeper detail (.env handling, failure modes), see Cloudflare-native local development.

Prerequisites

  • Node 22, pnpm 10 (corepack enable)
  • Local clone with submodules: git clone --recurse-submodules ...

Initial setup

Terminal window
pnpm install
cp .env.example .env    # then set dev-auth values (see below)


# D1 migrations + dev tenant seed (local wrangler state)
pnpm dev:bootstrap


# Package watchers + gateway (wrangler dev) + agent (tsx watch)
pnpm dev

Readiness banner: [mnemose-dev] Core runtime ready. Health check: curl localhost:4000/health → {"status":"ok","service":"mnemose-gateway","runtime":"cloudflare-workers",...}

GraphQL at http://localhost:4000/graphql enforces auth: {"errors":[{"message":"Missing Authorization header","extensions":{"code":"UNAUTHENTICATED"}}]} is the expected unauthenticated response.

.env (required by tsx --env-file)

services/*/package.json dev scripts load --env-file=../../.env. Without that file tsx exits 9 (node: ../../.env: not found). Copy the example and ensure:

  • DEV_AUTH_BYPASS=true
  • DEV_AUTH_TENANT_ID=11111111-1111-4111-8111-111111111111

The bootstrap seed (scripts/bootstrap-local-dev.mjs) relies on both. It seeds two tenants: the dev tenant (1111...) and the canonical child tenant “Acme Cloud” (22222222-2222-4222-8222-222222222222) where operational data lives.

What pnpm dev actually runs

scripts/dev-runtime.mjs starts, in order:

  1. Package watchers — logger, kernel-protocol, bootstrap, db, domain, and peers build in watch mode so changes propagate to consumers.
  2. Gateway — wrangler dev (workerd) with the bindings from wrangler.toml (D1, R2, KV, Queues, DOs against local state).
  3. Agent — tsx watch persona runtime.

Run the console separately (cd apps/console && pnpm dev, :3200, Vite proxies /graphql to the gateway).

Command/job handlers run Workers-edge inside the gateway queue consumer; you can also watch them directly:

Terminal window
pnpm dev:handlers

Reset local state

Terminal window
rm -rf .wrangler          # wipes local D1, KV, queue state
pnpm dev:bootstrap        # re-apply migrations + seed

The seed is idempotent (INSERT OR IGNORE).

Tests

Terminal window
pnpm -r test
pnpm --filter @mnemose/domain test

Next

→ 7. Add a command flow