Skip to main content
This page covers running Spillway’s own server and dashboard from source. If you just want to send requests through a hosted instance, skip to the Quickstart instead.

​
Requirements

  • Node ≥ 22
  • pnpm 10
  • Docker (for local Postgres and integration tests)
You do not need a WorkOS account or provider API keys to work on most of the codebase. Integration tests mint their own JWTs, and provider calls run against recorded fixtures.

​
Set up

1

Install dependencies

2

Configure environment

Copy the example env file and fill in what you need — most variables are optional in development.
Never commit .env. It’s gitignored on purpose.
3

Start Postgres

Local dev and tests run against Dockerized Postgres.
4

Seed data (optional)

Mints a demo org, team, and a virtual key you can use immediately.
5

Run the server and dashboard

​
Two auth modes for local dev

Spillway’s dashboard authenticates humans through WorkOS AuthKit. You have two options locally:
  1. Real WorkOS auth — set WORKOS_API_KEY and WORKOS_CLIENT_ID in .env (use WorkOS’s Staging environment’s test keys).
  2. No auth provider at all — integration tests mint their own JWTs directly, so you can work on most of the codebase without ever touching WorkOS.
Data-plane requests (the gateway itself) never go through WorkOS — they authenticate with a virtual key, independent of human auth.

​
Quality gates

One command has to pass before a change is done — it’s the same thing CI runs:
Useful subsets while iterating:
Integration tests need Docker running. Avoid running pnpm stress within ~15s of an integration run — the previous session’s container reaper can sweep the stress harness’s containers mid-run and produce a confusing failure.

​
Regenerating the API reference

The API reference is generated, not hand-written — the request/response schemas are the single source of truth, so the spec can’t drift from what the server actually validates:

​
Where next

Quickstart

Make your first request against the server you just started.

Architecture

What pnpm dev actually boots, and how a request flows through it.