Local development

Bring up infrastructure


docker compose up -d        # Postgres + Redis only (apps run via pnpm)

Install dependencies


corepack enable             # get pnpm 9
pnpm install

Configure the environment

Create .env.development at the root per Configuration (at minimum DATABASE_URL + CLERK_SECRET_KEY; platform-api also needs ENCRYPTION_SECRET_KEY).

Build the workspace packages (order matters)

@magic/db runs prisma generate, so it must come first. pnpm build runs pnpm -r build in topological order and builds all six packages (db, shared, util, openai-compat, cliproxy, testing):


pnpm build

Run database migrations

Apply the committed migrations to bring your database up to date:


pnpm prisma migrate deploy

Only run pnpm prisma migrate dev when you’re authoring a new migration after editing schema.prisma.

Start the services


pnpm dev              # all apps in parallel: platform-api:3111, agent-service:3112, gateway:3110, relay:3113, keeper:3114
# or individually:
pnpm start:platform   # platform-api  (:3111)
pnpm start:agent      # agent-service (:3112)
pnpm start:gateway    # gateway       (:3110)
pnpm start:relay      # relay         (:3113)
pnpm start:keeper     # keeper        (:3114)

relay and keeper drive the CLIProxyAPI account pool. They start fine without it, but serving real /v1 traffic or ingesting usage needs a reachable cliproxy (see Deployment).

Confirm it’s up


curl http://localhost:3112/api/health

Why build order matters

The build dependency graph is @magic/db (prisma generate) → @magic/shared → apps, with @magic/util, @magic/openai-compat, @magic/cliproxy, and @magic/testing as leaf packages. Tests and apps import from each package’s dist, not its source — so pnpm build (topological) must run before you run tests or start a service.

Common commands

Command	What it does
`pnpm dev`	Run all apps (platform-api, agent-service, gateway, relay, keeper) in parallel
`pnpm -r build`	Build all workspace projects
`pnpm -r test`	Unit + contract tests
`pnpm -r test:int`	Integration tests (Testcontainers; needs Docker)
`pnpm lint` · `pnpm format`	ESLint / Prettier
`pnpm prisma <cmd>`	Proxy to `@magic/db`’s prisma command

After editing packages/db/prisma/schema.prisma you must generate a migration: a Husky pre-commit hook runs prisma migrate diff --exit-code and blocks the commit if the schema and migrations/ are out of sync.