Stop juggling terminal tabs.
One binary that starts your services in the right order, waits for them to actually be ready, and cleans up properly when you stop.
You know this.
Postgres in one tab, Redis in another, API in the third. You close your laptop, reopen it, and nothing works. You spend five minutes figuring out what to restart and in what order.
kb-dev start. One command. Everything comes up in the right order.
You run your service and get "address already in use". Something is holding port 3000. You do ps aux | grep node and squint at a list of processes hoping to guess which one it is.
kb-dev doctor tells you exactly what owns the port and gives you the command to fix it.
You run make dev, everything looks like it started, but the API crashes immediately. Postgres wasn't up yet. You re-run. Sometimes it works, sometimes it doesn't.
kb-dev waits for the health check to pass before starting anything that depends on it. No races.
One file, any project.
Drop devservices.yaml in your project root. kb-dev finds it automatically by walking up from the current directory.
KB Labs projects use .kb/devservices.yaml — same format, different location.
name: my-project
services:
postgres:
type: docker
command: docker run --rm -p 5432:5432 postgres:16
health_check: http://localhost:5432
port: 5432
api:
command: pnpm dev
port: 3000
health_check: http://localhost:3000/health
depends_on: [postgres]
worker:
command: pnpm worker
depends_on: [postgres]How it works
The things that matter once the pain is familiar.
Knows when a service actually died
Tracks the real PID because it spawned the process. No port scanning, no stale state, no guessing.
Doesn't call it alive until it actually responds
HTTP, TCP, and command health probes with response latency. Reports alive only after the check passes.
Starts postgres before the thing that needs postgres
Topological sort across your services. Parallel start within each layer, correct order guaranteed.
Brings it back without you watching the terminal
Watchdog with exponential backoff. A crashed service restarts automatically, up to 5 retries.
Stops the whole tree, not just the parent
Uses process group kill to stop the entire subtree. No orphaned child processes left behind.
Every command is scriptable
Every command outputs structured JSON with an ok field. Failures include a hint with the exact fix. Works in CI, Makefiles, and agent workflows.
Commands
All commands support --json for scripting and agent workflows.
kb-dev startStart all services in dependency order. Pass a group or service name to target.
kb-dev stopStop services. Use --cascade to also stop everything that depends on the target.
kb-dev statusStatus table with health latency. --json returns structured output with depsState.
kb-dev ensure api workerIdempotent desired state: alive services are skipped, dead ones are started.
kb-dev ready api --timeout 30sBlock until the service is alive. Use as a gate in CI or agent workflows.
kb-dev logs api --followStream live logs for a service. Omit --follow for a tail of the last 50 lines.
kb-dev doctorCheck the local environment: node, docker, port conflicts. Returns hints for every issue.
kb-dev watch --jsonStream lifecycle events as JSONL: health, crashed, restarting, alive.
Download
Pre-built binaries for macOS, Linux, and Windows. SHA-256 checksums included in every release.
Part of KB Labs
kb-dev ships as a standalone tool and as part of the KB Labs platform. When you install KB Labs, kb-dev is included automatically.
Install KB Labs →