devstack › Guide
devstack is a single static Go binary that manages Docker-based dev environments and shares infrastructure across projects — one warm Postgres/Redis/MinIO (and Kafka/NATS/RabbitMQ/LocalStack) on a tool-owned network for many repos, instead of a duplicate stack per repo. This guide is the task-oriented companion to the specs: examples first, real flags and fields only. Work through it top-to-bottom, or jump to the page you need.
New here? Read them in this order: Concepts → Installation → Workspaces → Projects → Lifecycle. That's the shortest path from zero to a running workspace.
| # | Page | What it covers |
|---|---|---|
| 1 | Concepts & the mental model | The four nouns, the two-file model, the shared network, no daemon, the up saga. |
| 2 | Installation, doctor & updates | Install the binary, verify your host with doctor, self update. |
| # | Page | What it covers |
|---|---|---|
| 3 | Workspaces | workspace.yaml and init. |
| 4 | Projects | devstack.yaml and its services. |
| 5 | Environment variables | Local key-value env vars with no external store (env.raw/prefixed/import). |
| 6 | Templates | Using and authoring service templates. |
| # | Page | What it covers |
|---|---|---|
| 7 | Lifecycle | up, down, status, shell, logs, dashboard. |
| 8 | Shared services & host access | The shared engines, shared expose, shared ports. |
| # | Page | What it covers |
|---|---|---|
| 9 | Databases (Postgres) | The db group — tenant databases, roles, grants. |
| 10 | Object storage (S3/MinIO) | The s3 group — tenant buckets, lifecycle, policy, CORS. |
| 11 | Messaging | queue, topic, stream on NATS/Kafka/Redis/LocalStack. |
| 12 | The resource layer | The resource group + declarative resources:. |
| 13 | Snapshots, restore & reset | db snapshot/restore/reset/pull. |
| # | Page | What it covers |
|---|---|---|
| 14 | Multi-repo git | The ws group — clone, sync, status across repos. |
| # | Page | What it covers |
|---|---|---|
| 15 | Secrets | The secrets group, secret://, and .env ingest. |
| 16 | Local HTTPS & DNS | dns, trust, the local proxy. |
| 17 | Public tunnels | The tunnel group (cloudflared). |
| # | Page | What it covers |
|---|---|---|
| 18 | Recovery, teardown & housekeeping | doctor --fix, shared doctor, gc, workspace destroy, uninstall. |
| 19 | The global store (~/.devstack) | The store group — config, templates, shared, snapshots. |
| 20 | Aliases & argv[0] dispatch | The alias group and --as. |
| 21 | AI agents | The ai group — docs, the command catalog, JSON Schemas, and the rules an agent must follow. |
| # | Page | What it covers |
|---|---|---|
| 22 | Full config reference | Every workspace.yaml / devstack.yaml field + the grammars. |
| 23 | Command reference | Every command, terse, grouped by area. |
| 24 | Global flags & scripting | --json/--quiet/--debug/--verbose, the --yes rule, --check, CI recipes. |
| # | Page | What it covers |
|---|---|---|
| 25 | What's next: roadmap & current gaps | What ships today vs. what's on the roadmap or still a gap. |
◀ devstack index · Guide index · Concepts & the mental model ▶