On this page

Defined in cli/commands/pool.ts. Reserves, resets and hands back the machine's fixed checkouts — the main checkout, .worktrees/wt1 and .worktrees/wt2 — with a lease. It skips the wrapper's AWS gate and stage bind: everything except cloud mode touches only local Docker. See The checkout pool for how the pieces fit together.

Every subcommand except status names the session holding the lease — pass --session <name>, or set DEVSTRIDE_SESSION once in your shell. <checkout> is always main, wt1 or wt2.

The lease also records which session took it. Two sessions can share a name, so the name alone proves nothing. Each lease carries a holder: the Claude Code session id and/or the Codex thread id, which every command in that session shares. reset, client, release-client, cloud, checkin, template refresh and ds work refuse anyone but that holder, even under the same session name. From a plain terminal, which has neither id, checkout prints a one-time token — run the export DEVSTRIDE_LEASE_TOKEN=… line it prints, and every later command in that shell proves it is you. A lease written before holders were recorded is refused by all of those commands; hand it back by hand only if you are sure it is yours, otherwise it is the owner's to clear.

ds pool status#

ds pool status

Who holds each checkout (session, purpose and time — marked STALE once a lease is over 24 hours old; clearing it is the owner's call), what branch it is on, and what data it holds: golden, one customer's organization (flagged for review after 14 days), or bound to a cloud stage. It also reports how old the golden template is, and any containers no pool checkout owns — reported, never removed. No flags.

ds pool checkout#

ds pool checkout <checkout> --purpose <text> [--session <name>] [--mode client --org <id> | --mode cloud] [--i-know-main-is-free]

Takes the checkout's lease and starts its app. Prints exactly one outcome:

Outcome Meaning Exit code
LEASED The checkout is yours. Its Docker app is started (or, with --mode cloud, its cloud app), unless Docker has less than about 3 GB of memory free, when the start is refused with how much is free and what to stop (Troubleshooting). Re-running checkout on a checkout you already hold says you already hold it; nothing was changed. If the previous holder kept a customer copy there, a NOTE names it. 0
BUSY Another session holds the lease; the line says who and why, and that you do NOT hold it — even when the other session uses your name. Message them or take the other checkout. Never delete someone else's lease. 2
IN USE No lease, but the checkout is dirty or on someone's branch — a session from before the lease rule is working there. Your lease has already been released; take the other checkout. 2
Flag Description
--purpose <text> Required. What you are using it for, e.g. an item number
--session <name> Who holds it. Default: DEVSTRIDE_SESSION
--mode <mode> client copies one organization in (needs --org); cloud runs the checkout against this machine's own stage. Omitted: local Docker, keeping whatever data it already holds
--org <id> With --mode client: the organization to copy in
--i-know-main-is-free Required to reserve main, which is the owner's own checkout — only after they say it is free

The lease is a file in the checkout's own git directory, so it never dirties the tree, and it is created only if it does not already exist, so exactly one session can win it.

ds pool checkin#

ds pool checkin <checkout> [--session <name>] [--keep-client]

Hands the checkout back. Stop every process you started there first (test runs, dev servers, watchers). It refuses unless you hold the lease and the tree is clean, and refuses a detached checkout holding commits no branch contains. It then ends any cloud binding, stops the checkout's app containers (its test containers keep running), leaves it detached at a freshly fetched origin/develop, and removes the lease. Its data is kept.

It refuses while the checkout holds a customer copy (client mode), unless you pass --keep-client. Why: a customer's data left behind by accident is the one thing nobody notices. Drop it first with ds pool release-client <checkout>, or keep it on purpose with --keep-client — the next session to check the checkout out is told it is there.

ds pool template refresh#

ds pool template refresh --from <wt1|wt2> [--session <name>]

Captures the golden template that resets clone from. Run it from a leased wt1 or wt2 that has just run ds worktree cli <checkout> golden build — never main. It refuses a checkout in client mode, one whose database holds any organization that is not golden, and one whose database holds no golden organization at all (… holds no golden organization — run its golden build first), which would capture an empty template.

ds pool reset#

ds pool reset <checkout> [--discard-other-orgs] [--session <name>]

Snaps a leased checkout's data back to its snapshot in seconds, instead of a full golden rebuild: the golden template, or — in client mode — that checkout's own copy of the customer's organization. A golden reset also re-creates the golden logins in the checkout's own Cognito pool.

  • The database holds organizations besides the demo data (a customer copied in with ds worktree cli <checkout> data copy, which the pool does not record): a golden reset refuses, names up to three of them, and gives the command to run if they are not needed. --discard-other-orgs replaces the database anyway. A database whose organizations cannot be read is refused the same way.

  • Only the demo logins failed: the data is already in place, and the error says so and names the command to rerun, ds pool reset <checkout> (or ds pool release-client <checkout> when that was the command). When the cause was Docker's memory, it says that too (Troubleshooting).

  • Your branch is ahead of the snapshot: it clones, runs your branch's migrations, and checks that every one of them actually landed.

  • Your branch is behind the snapshot: refused. A clone would be ahead of your code and nothing downgrades it — rebase, or refresh the template from a checkout at your branch's migrations.

  • The checkout is cloud-bound: refused until ds pool cloud <checkout> --off.

ds pool client#

ds pool client <checkout> --org <id> [--session <name>]

Client mode for a checkout you already hold (the same as ds pool checkout … --mode client --org <id>): copies one customer's organization into the checkout's own database, then keeps that copy as its snapshot, so every later ds pool reset snaps back to it without copying again. It reads SOURCE_DB_CONNECTION_STRING, as ds data copy does. A checkout already holding a different organization is refused, so two customers' data never share one checkout.

ds pool release-client#

ds pool release-client <checkout> [--session <name>]

The only way out of client mode by hand. It resets the checkout to golden first, and only once that has worked does it drop the customer snapshot — a reset that fails changes nothing. The unattended ds machine doctor also does this for a copy older than 14 days on a checkout no one holds.

ds pool cloud#

ds pool cloud <checkout> [--off] [--session <name>]

Moves a checkout you hold from local Docker to this machine's own cloud stage — one checkout per machine at a time. Also reachable as ds pool checkout <checkout> --mode cloud.

  • The stage comes from the checkout's .env — the machine bundle's DEVSTRIDE_STAGE, DEVSTRIDE_DEV_PROFILE and NEON_BRANCH, written by ds secrets pull — falling back to your shell's environment. DEVSTRIDE_REGION defaults to us-east-1.
  • It refuses the shared dev, staging and prod stages, a machine where sst dev is already running, and a second checkout while one is already bound.
  • It checks the AWS identity first and never opens a login. A lapsed login gets the exact aws sso login --profile <profile> command; a refused machine identity says so.
  • It brings the stage's database up to the checkout's code first. Before anything is stopped or started, it compares the stage database's migrations with the checkout's. Missing ones are applied from the checkout (the same ./ds -b migrations run a new stage gets) and checked to have landed; if that fails, the checkout stays on Docker. A stage database ahead of the checkout's code is refused, because nothing downgrades a database: bring the checkout up to date, then bind again. The check reads the database with the local core Postgres container's psql, so ds worktree core up must be running.
  • It stops the checkout's Docker app and starts ds run backend and ds run ui in the background, with the UI on the checkout's own frontend port and logs in .ds/pool-cloud-backend.log and .ds/pool-cloud-ui.log.

--off stops both, deletes that stage's .ds/bind file in the checkout (so nothing run there later is silently cloud-bound) and brings the Docker app back. ds pool checkin does the same unbinding, then hands the checkout back with its Docker app stopped. A binding whose app has stopped is reported as an error, never as "already bound" — run --off, then bind again.


Powered by DevStride