Install

Three ways to run Runkite, in order of how real they are: a laptop demo (SQLite, no auth, throw it away when you're done), the Supported Docker Compose profile (Postgres + Redis, this is the one to trust), and Kubernetes/Helm (same topology, packaged for a cluster). Pick based on what you're actually doing today.

Option 1 — laptop demo (5 minutes, not for anything real)

git clone https://github.com/getrunkite/runkite.git && cd runkite
docker compose -f docker-compose.dev.yml up -d --build

This uses SQLite and an in-memory job queue — everything runs in one container, nothing survives a restart, and there's no authentication at all. That's intentional: it's for kicking the tires and following First agent, not for anything you'd point real traffic at. If you just want to see it work without cloning anything, use Try it instead — same idea, zero setup.

Option 2 — Supported profile (Postgres + Redis)

This is the profile Runkite is actually tested and soaked against for multi-replica production use. Two things make it "Supported" instead of "it probably works": Postgres holds every agent/thread/run/audit record so a control-plane restart (or running 3 replicas behind a load balancer) never loses or duplicates state, and Redis is the shared job queue and locking layer so those replicas coordinate correctly instead of each thinking it owns the whole world.

Steps:

1. cp .env.example .env

   Open .env and fill in two values: POSTGRES_PASSWORD (any password — this stays inside your Docker network) and RUNNER_TOKEN (generate one with openssl rand -hex 32). Both are required — the stack refuses to start with a placeholder or empty value instead of silently booting with a well-known default password.

2. docker compose up -d --build

   This starts four containers: Postgres, Redis, the control plane, and a Python runner loading the bundled example agents.

3. curl -sf http://localhost:2026/readyz && echo OK

   /readyz doesn't just check that the HTTP server is up — it actually verifies Postgres and Redis are reachable. If this returns anything other than OK, check docker compose logs runkite before assuming your agent config is the problem.
4. Open http://localhost:2026/admin/ to confirm the plane sees the bundled example agents (see Admin UI guide for what you'll find there).

Client-facing auth is not turned on by this compose file. It sets RUNKITE_ALLOW_INSECURE_SERVE=1 specifically so the demo boots without you having to write an auth config first — this is fine on your own machine, but before this stack is reachable from anywhere else, add a real auth section to langgraph.json (see Admin login for the exact shape) and remove that env var. Without auth configured, RUNKITE_ALLOW_INSECURE_SERVE is required — the plane refuses to boot in an ambiguous "maybe secure" state.

Option 3 — Kubernetes / Helm

Same Postgres + Redis topology, packaged as a Helm chart under deploy/helm/runkite. Unlike the Compose demo above, the chart's default config does wire in real client auth out of the box — you supply the API key value, not a bypass flag.

1. Have a Postgres and Redis reachable from the cluster — the chart does not bundle them; point it at infrastructure you already run.

2. helm upgrade --install runkite deploy/helm/runkite \
     -f deploy/helm/runkite/values.yaml \
     -f deploy/helm/runkite/values-supported.yaml \
     --set secrets.postgresDsn="postgres://..." \
     --set secrets.redisUrl="redis://..." \
     --set secrets.apiKey="$(openssl rand -hex 32)"

3. Optional: add -f deploy/helm/runkite/values-tls.yaml for pod-to-pod TLS/mTLS between the control plane and runners.
4. Check rollout: kubectl get pods -l app.kubernetes.io/name=runkite, then port-forward or hit your Ingress's /readyz.

Kubernetes packaging itself has been proven with kind (install, runner token rotation, mid-run reclaim, and Ingress/NetworkPolicy — run the whole suite with make kind-helm-all) and with a named smoke test on real EKS (install, a real run, and a control-plane pod kill recovering cleanly — see k8s-eks-soak-results.md). What's not proven yet on cloud Kubernetes is a long, multi-availability-zone HA soak — the Compose multi-replica soak is still the deeper correctness proof today. Until that longer cloud soak exists, treat a Kubernetes install as "packaging and day-1 ops are solid" rather than "identical HA guarantees to Compose."

What to expect

• "/readyz never turns healthy." — almost always Postgres or Redis isn't reachable yet, or the DSN/URL is wrong. Check docker compose logs / pod logs for the exact connection error before touching anything else.
• "serve refuses to start." — this is usually intentional, not a bug: production admission checks fail closed on an insecure combination (e.g. runner tokens configured but no matching RUNNER_TENANTS_*). The startup log names exactly which check failed.
• Required secrets fail loudly, not silently — an unset POSTGRES_PASSWORD/RUNNER_TOKEN stops the stack from starting at all, instead of quietly deploying with a shared default password everyone forgets to change.

Reference: docs/deployment.md · docs/configuration.md · Production day-0 · Ops