Guide

Local Development

Run a full Kite stack on your laptop — CLI, relay server, and Postgres — for offline testing and CI.

The Kite CLI talks to a relay server over WebSocket. For most development you should use the hosted relay; the Docker stack is for internal server development and CI only.

// 01Option A — Use the hosted relay

For most app development, you don't need a local server. Run the CLI against the hosted relay and let the events flow back to your machine:

bash

kite login
kite proxy --source github --target http://localhost:3000/webhooks

This is what the Quickstart covers. No containers, no schema, no secrets to manage.

// 02Option B — Internal local stack via Docker

When you need an offline dev loop, tests that don't depend on the internet, or a place to iterate on server behavior, spin up the local stack:

bash

git clone https://github.com/Alpha-Centauri-Cyberspace/kite-server.git
cd kite-server
docker compose --env-file infra/local/.env -f infra/local/docker-compose.yml up -d --build

The stack includes Postgres, the relay server, and the web dashboard. Minimum env:

Variable	Required	Notes
`POSTGRES_PASSWORD`	yes	Any strong value — compose creates the DB
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	yes unless `KITE_LOCAL_DEV_AUTH=1`	Web dashboard auth
`CLERK_SECRET_KEY`	yes unless `KITE_LOCAL_DEV_AUTH=1`	Dashboard + API auth
`KITE_LOCAL_DEV_AUTH`	no	Set to `1` for a deterministic local dashboard user on localhost only
`KITE_CORS_ORIGIN`	no	Defaults to `http://localhost:8080`
`KITE_HOOK_SECRET_CIPHER_KEY`	yes for provider signing secrets	Enables per-endpoint secret storage at rest

For dashboard UI work, you can bypass hosted Clerk sign-in locally:

bash

KITE_LOCAL_DEV_AUTH=1 pnpm --dir apps/web dev

This mode only activates outside production and only for local hosts such as localhost, 127.0.0.1, or ::1. It uses the deterministic team dev_user_local and still creates the normal team, free subscription, and wallet rows in Postgres. Leave KITE_LOCAL_DEV_AUTH unset when testing real Clerk flows.

Point the CLI at the local server:

bash

kite login --server http://localhost:8080

From here, kite stream and kite proxy talk to your container instead of the hosted relay.

// 03Serving real webhooks to localhost

The relay needs a public URL for third-party sources (GitHub, Stripe, Linear) to reach it. In local dev you have three options:

Use the hosted relay (Option A) — the webhook_url printed by kite endpoints create already works from the internet.
Put a tunnel in front of the local server (e.g. cloudflared tunnel, tailscale funnel) and register that URL with your source.
Generate events manually with curl against the local /hooks/<team>/<source>/<token> endpoint — useful in tests.

// 04Running tests against the local stack

Use the CLI's exec sink to run an assertion script per event. Combined with a fixture generator, this gives you a deterministic end-to-end test loop.

bash

kite stream --source github --exec ./test/assert-event.sh

assert-event.sh reads the CloudEvent JSON from stdin and exits non-zero if something's off.

// 05See also

Deployment — hosted production operations
Troubleshooting — common "CLI can't reach server" failures