devstack

Your whole stack, always running the code you saved, never a broken build.
Native services, their containers, every git worktree beside it, and when your
laptop runs out of room, the team's server: one CLI, one dashboard, one MCP
server for your coding agents.

devstack up        # infrastructure, builds, every service: healthy or it says why
devstack ui        # every stack, live, in the browser

• Save, and it is live, or it says why not. A change builds as a
  candidate beside the running instance and takes over only once it is
  healthy. A compiler error leaves the old build answering; devstack status
  says not yet active: building | failed | held until your change runs.
• Every worktree is a lane. git worktree add and devstack up in it: the
  same stack on its own ports, with its own containers and data, beside the
  main one. Ten agents on ten branches, no collisions.
• Lanes on other machines. devstack up --on build-server runs a
  worktree's lane on a machine of the team's pool, its ports forwarded to
  yours as if it ran locally. Move it back with one command, share it with a
  reviewer, give it the main ports.
• Made for agents. An MCP server and generated skills let coding agents
  start, check, fix and move the stack, and know whether their change is live.
• Your files, no lock-in. Infrastructure comes from the Compose files you
  deploy with; services from a short devstack.toml. devstack env api --export dotenv runs any service without devstack.
• Windows and Linux, natively. One static binary, no WSL required.

Before 1.0 · local stacks, lanes and the pool are in daily use on .NET, Node and
Angular stacks. See what is planned and
the decisions behind it.

Install

# Windows: to %LOCALAPPDATA%\Programs\devstack, on PATH
irm https://github.com/nuetzliches/devstack/releases/latest/download/install.ps1 | iex

# Linux (x86_64, static): to ~/.local/bin
curl -fsSL https://github.com/nuetzliches/devstack/releases/latest/download/install.sh | sh

On Windows, winget install nuetzliches.devstack installs the same build
(releases after 0.15.0, once winget's catalogue has them, usually a few days
after the release); devstack update then updates it through winget, and
the first devstack up registers the hub as the installer would.

The scripts and devstack update check the download against the release's
SHA256SUMS: that proves the archive is the one the release lists (not
damaged or swapped on the way), not who built it, since both come from the
same release. Each release also carries a build provenance attestation; with
the GitHub CLI installed and logged in, the scripts
verify it (gh attestation verify <archive> --repo nuetzliches/devstack):
built by this repository's release workflow (releases from 0.10.0 on). The
Windows executable is not code-signed, so SmartScreen or an endpoint
protection product may warn about it at first (SECURITY.md). The
landing page tells whether your
machine is ready. devstack update (or the dashboard) installs a newer
release; devstack self uninstall removes devstack again. From source: cargo install --git https://github.com/nuetzliches/devstack devstack (without the
dashboard: it needs npm ci && npm run build in ui/ before the build;
devstack update leaves such a binary alone).

The installer registers the dashboard hub to start at logon and a
devstack:// link the dashboard uses to start it. To skip both, set
DEVSTACK_NO_HUB_INTEGRATION=1 before the install command (Windows also
takes -NoHubIntegration when the script is run as a file); the choice is
kept, so devstack up does not register them later either. devstack hub install adds them, devstack hub uninstall removes them again.

Start

devstack init              # a first devstack.toml from the repository (TODOs to work through)
devstack doctor            # is this machine ready: Docker, Compose, tools, ports
devstack up                # daemon, infrastructure, every autostart service
devstack ui                # the dashboard
devstack skills install    # skills for your coding agent, filled in from the stack file

A stack file names the Compose files of the infrastructure and the services
devstack builds and runs:

version = 1

[stack]
name = "shop"

[compose.app]
project  = "shop-dev"
files    = ["deploy/compose.yml"]
services = ["db"]

[services.api]
build  = "dotnet build src/Api -c Debug"
output = "src/Api/bin/Debug/net9.0"
run    = "{artifact}/Api"
port   = 5000
health = { http = "/health", timeout = "60s" }
watch  = ["src/Api/**"]
env    = { ConnectionStrings__Db = "Host={compose.app.db.5432}" }

[services.web]
kind = "devserver"
run  = "npm run dev -- --port {port}"
port = 4200

The full reference: docs/stack-file.md; devstack schema prints the JSON Schema for your editor.

Every day

devstack status                    # every service; "not yet active" until your change runs
devstack logs api --follow         # --grep timeout across all, --since 2h for earlier instances
devstack restart api               # rebuild now; the running one stays until the new one is healthy
devstack promote api               # take over a candidate held back by a schema change
devstack rollback api              # back to the build before the last replacement
devstack builds api                # did my change ever go live, since when is it broken
devstack hot-reload api on         # the toolchain's own watcher, for a debugging session
devstack run reset                 # a command of the stack file (a database reset, say)
devstack top --watch               # CPU, memory, disk per service, container, group and lane
devstack env api                   # what a service gets, with origins
devstack logs --daemon             # devstack's own decisions with their reasons
devstack down [--infra] [--all]    # running lanes keep the daemon; --all stops them too

Lanes: every worktree, side by side

git worktree add ../shop-login -b login-fix     # a worktree is a lane at once
cd ../shop-login && devstack up                 # its own builds, ports +100, its own containers
devstack lane start login-fix                   # the same, from the main tree
devstack lane list                              # every lane, where it runs, who has the main ports
devstack promote --lane login-fix               # it answers on the main ports; --lane main gives them back
devstack lane stop login-fix

A lane runs from a copy of its worktree, so git can remove the worktree while
it runs. It gets its own Compose project and data (seed jobs fill it), and no
background workers unless it holds the main ports.

The pool: lanes on other machines

devstack join https://10.0.0.5:4260 --fingerprint <fp>   # once; an admin approves
devstack up --on build-server        # in a worktree: everything of the lane runs there
devstack up --on pool                # the coordinator picks a node
devstack lane move login-fix --to local
devstack lane share login-fix --with team:qa
devstack open login-fix web          # a lane someone shares with you

One machine runs the coordinator, servers run a node agent; the dashboard's
pool area admits members, shows capacity (GPUs included) over time, and sets
what each node runs (who, which repositories, limits, network). Several pools
per machine, a customer's beside the team's. Setup and everything else:
docs/pool.md.

Agents

devstack mcp is an MCP server on stdio, a client of the same API as the CLI:
status, up (with on for a node), down, start_service,
stop_service, restart_service, promote_service, rollback_service,
hot_reload, logs, builds, diagnostics, doctor, run_command,
usage, lanes, lane_start, lane_stop, lane_move, lane_share,
promote_lane, placement, hub_status, hub_start.

{ "mcpServers": { "devstack": { "command": "devstack", "args": ["mcp"] } } }

devstack skills install writes two skills into the repository
(.claude/skills/ by default; [agents] skills in the stack file names the
folders, .agents/skills for Codex and most other agents):
devstack (operating this stack, "is my change live", troubleshooting)
and devstack-config (editing the stack file). They are filled in from
the stack file; devstack status says when they are out of date. A command with a confirmation text in the stack file runs only
when the agent passes confirm: true, which it may only do after you agreed.

Commands

Every command and flag: devstack --help, devstack <command> --help.

Why

Most local orchestrators run a service straight out of the working tree's
build output and restart it whenever a file changes. With one developer that
is tolerable. With an IDE, several terminals and several AI agents editing the
same tree, it gives a stack that is half-built, file-locked, restarted three
times a second, and impossible to ask "is my change running?".
docs/problem-statement.md describes the failure
modes devstack removes.

Shape

devstack CLI ──┐                    ┌── infrastructure: docker compose, health-gated
MCP (agents) ──┼──► devstackd ──────┼── builds: snapshot → build → artifact <build-id>
dashboard ─────┘    one per repo,   └── services: main slot (fixed ports) + candidates,
   │                loopback API          lanes (worktrees) on their own ports
   └── hub (every stack, the pool) ──► coordinator ──► node agents (lanes of others)

Environment

Documentation

Contributing

Documentation, code and commits in English. Architectural decisions are
recorded as ADRs before they are built (AGENTS.md). The project
is generic: downstream stacks keep their stack file, Compose files and secrets
in their own repositories.

License

MIT or Apache-2.0, at your option (LICENSE-MIT,
LICENSE-APACHE). Security reports: SECURITY.md.