Local Development

Overview

The graphdb dev command wraps wrangler dev --local and boots the complete stack on your machine:

Service	Local equivalent
Cloudflare Workers	Miniflare in-process runtime
Durable Objects (GraphShard)	Miniflare DO emulation
D1 (graph metadata)	Local SQLite file
KV (schema cache)	In-memory KV store
Vectorize	In-memory vector index
R2 (backups)	Local filesystem bucket

No cloud account is needed. No billing surprises.

Prerequisites

Node.js 20+
pnpm 9+
Cloned core repository

Getting started

Install dependencies
Terminal window
```
pnpm install
```
Copy the environment example
Terminal window
```
cp .env.example .env
```

Start the local stack

pnpm graphdb dev

You should see output like:

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
  graphdb-labs local stack
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
✓  D1 database ready     (local SQLite)
✓  GraphShard DO ready    (Miniflare)
✓  KV store ready
✓  Vectorize index ready
✓  API listening on       http://localhost:8787

Create your first graph

curl -X POST http://localhost:8787/graphs \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{"name": "my-graph", "description": "Test graph"}'

Trust header in local mode

In production, every request must carry a verified X-Internal-Sig trust header (issued by edge-gateway).
In ENVIRONMENT=development, the trust middleware automatically bypasses signature verification and accepts any X-Tenant-Id you provide.

CLI commands

Command	Description
`pnpm graphdb dev`	Start local stack
`pnpm graphdb schema push`	Push schema changes to local D1
`pnpm graphdb schema generate`	Generate Drizzle migration files

File layout for local state

core/
└── .wrangler/
    └── state/
        ├── d1/          ← local SQLite files
        ├── kv/          ← KV store snapshots
        └── r2/          ← R2 bucket files

Delete this directory to reset all local state.