ds machine
On this page
Defined in cli/commands/machine.ts. It sets up and maintains the machines that work on DevStride: setup takes a bare machine to ready, ready proves it works, and doctor keeps its checkouts current. The rest give each unattended agent machine its own certificate per AWS account. A machine with nobody at the keyboard cannot finish aws sso login, so an expired session would stall it mid-task. With a certificate, IAM Roles Anywhere exchanges it for a short AWS session named after the machine. There is no login and no 8-hour expiry, and every action in CloudTrail names the machine that took it. People keep using SSO; certificates are only for machines. ds machine skips the wrapper's AWS gate: each subcommand that reaches AWS checks the account with the profile it was given.
For the whole sequence on a new machine, follow Set up your machine.
Treat these keys as production credentials
A machine identity works in both the dev and production accounts. The certificate authority's key, and each machine's own key, therefore need the same care as a person's production login.
Where the certificate authority lives. Its key and its record of every certificate issued are two secrets in the management account's Secrets Manager (devstride/machine-identity/ca-key and ca-state), not on any laptop. So ca-init, sign, revoke and issued run from any machine signed in to the management account: the devstride-mgmt profile, or DEVSTRIDE_MGMT_PROFILE, or --mgmt-profile <profile>. Each checks the profile really reaches the management account before reading either secret. The key is read into memory for one operation and never written to disk. Two people signing or revoking at once cannot corrupt the record: a save that would overwrite someone else's stops with "the CA state changed while this ran". Run the command again.
./setup and ds machine setup#
./setup [--agent <name> [--own] | --laptop] [--dry-run] [--yes] [--skip <stages>] [--timer]
./setup, at the root of the clone, is the one way to set up a machine, and to keep one current. It refuses to run inside a git worktree of the clone (wt1, wt2 or any other), and names the clone to run it in. Before anything else it brings the clone up to the latest develop, so setup runs today's code, but only when the clone has nothing of its own to lose: on develop or detached on it, with no commits develop lacks, and no changed file that does not already read as develop has it. It asks once at a terminal (--yes moves it without asking, a run with no terminal only reports it, and --dry-run never fetches or moves); otherwise it says why in one line and carries on with the code the clone has. After moving it starts again on the new code. On a blank Mac, the one line in the README (and in Set up your machine) installs Homebrew and the GitHub CLI, signs in to GitHub, clones the repository and runs it. ./setup installs what setup itself needs to run (Homebrew when it is missing, mise, Node and pnpm at the versions mise.toml pins, and the repository's dependencies), then hands every option to ds machine setup. Running it again is always safe.
ds machine setup checks everything first, lists every change it would make, every step that waits for a person, and every change to what the agents may do (Claude Code's settings and its trust in this repository, and Codex's approval of the repository's hooks), and asks once. At a terminal the question is a short Plan screen: how many steps fall under each heading, the changes to what the agents may do in full, and the choices y (Proceed), n (Stop), d (show every line of the plan) and s (name a later stage to leave alone this run). Enter alone means Stop; only a typed y goes ahead, and it covers all of it. On a machine set up before, the plan first lists what is Already in place now, such as a stage that is already built. Each later moment that needs a person is a screen of the same kind, with its choices and what each does. Then it applies each change and checks it again. A step that fails is reported with its reason, and everything that does not depend on it still runs. It works through eleven stages in order:
| Stage | What it takes care of |
|---|---|
tools |
The Brewfile tools (the AWS CLI, gh, git, jq, Neon's CLI, OpenSSL 3, psql from postgresql@15, linked onto the PATH only when no psql is there, and poppler), Node and pnpm at the pinned versions, the dependencies, and AWS's credential helper (aws_signing_helper, checked against its published checksum) |
containers |
Docker Desktop installed (its installer accepts Docker's licence and asks for the Mac password), started, and checked for at least 4 CPUs and 8 GB; on a Mac with 32 GB or more, for half the Mac's memory, up to 24 GB, which three checkouts and the demo-data build need together. Raising it is a step for a person: setup names the size and where to set it, and never changes Docker's settings itself. On a Mac with OrbStack or Colima, that runtime is used and started instead, and nothing is installed |
agents |
Claude Code and Codex installed and signed in; on a Mac, Codex's Homebrew cask upgraded when a newer one is out (Codex current, a step nothing else waits on); Codex's approval of the repository's hooks recorded (as its own /hooks screen would) and proven; Codex set to read all of AGENTS.md |
aws |
A person's machine: a self-renewing sign-in (an sso-session profile), then one browser sign-in. An agent machine: its own certificates for dev and production, issued from one approval, after which setup removes its own sign-in |
secrets |
Every checkout's .env, and the agents' credentials file, from ds secrets pull |
pool |
The main checkout's app running locally; wt1 and wt2 made, recorded, with their dependencies and their own generated types |
plugin |
The DevStride plugin in Claude Code and Codex (an install older than the repository needs is updated with the plugin's own verified updater, and Codex's copy is brought up to Claude Code's), the DevStride connection in each, Claude Code's settings for DevStride work and its trust in this repository (allowed by the one Proceed, never by --yes, and never when an agent runs setup) |
machine |
The GitHub sign-in, your git identity, Google Chrome with Claude in Chrome offered, the Claude and ChatGPT desktop apps, iTerm2 and Oh My Zsh (those four on a person's Mac only), the shell startup blocks (checked afterwards in a fresh login shell, and taken back out if they would change the Node or pnpm a terminal runs), ds on your PATH (~/.local/bin/ds), the docs clone, and the hourly check (agent machines, or --timer); on an agent Mac, keep-awake on mains power |
data |
The demo data, built once in a free wt1 or wt2, kept as the machine's snapshot, and copied into each checkout |
stage |
This machine's own AWS stage, built once with ds stage create (about 30–40 minutes, unattended), then checked; refreshed with ds stage create --refresh in a free wt1 or wt2 when its database is behind develop's migrations. Waits on the team's NEON_API_KEY |
proof |
ds machine ready: the verdict |
| Flag | Description |
|---|---|
--agent <name> |
An unattended agent machine with this name: its own certificate identity, keep-awake and the hourly check |
--own |
With --agent: you work at that agent machine too, so it also gets your own apps (the desktop apps, iTerm2, Oh My Zsh) |
--laptop |
A person's own machine (skips the question that asks) |
--dry-run |
Report what is missing and change nothing |
--yes |
Do not ask before the first change, nor before bringing the clone up to the latest develop. It never allows the changes to what the agents may do (Claude Code's settings and trust, Codex's hook approval) |
--skip <stages> |
Comma-separated stages to leave alone; a skipped stage counts as done, so a later step that relies on it still runs and reports what it could not do |
--timer |
Also install the hourly check on a person's own machine |
At the end it lists what changed and, when anything is left, Needs you (a step only you can do), Waiting on the above, and When you can (nothing waits on these). A machine that is already set up reports "Nothing to change." and still runs the proof. Its log is .ds/machine-setup.log, the demo-data build's is .ds/machine-setup-data.log, and the stage's first deploy writes .ds/stage-deploy.log in the checkout it deployed from.
ds machine ready#
ds machine ready [--quick] [--json]
Proves this machine works, and ends with READY or NOT READY. NOT READY names the first failing proof and its fix. Proofs are grouped as tools (including psql and pdftoppm), aws, github, devstride, checkouts, stage (this machine's AWS stage: recorded, stacks, config, database), landing, claude, codex, machine, agent machine, credentials and browser, and each line is one of: pass; FAIL, with its fix; held (another session is using that checkout, or Docker has too little memory free to start its app, so it could not be proven; not a failure); you (a step only a person can take); or note (something to do when you can; never a failure). READY means no proof failed.
| Flag | Description |
|---|---|
--quick |
Only the proofs that start no app and call no model, in seconds. The hourly check runs these and writes a ready: <group> result for each group to the fleet registry |
--json |
Print the verdict and every proof as JSON |
The full run also reserves wt1 and wt2 one at a time under setup's own session, starts each one's app and signs in as the demo user, runs the landing check in a free checkout, and asks Codex one line. With both checkouts free it takes several minutes, and prints its progress as it goes; its log is .ds/machine-ready.log. A run stopped part-way leaves a reservation that the next full run, ./setup or the hourly check takes back.
ds machine doctor#
ds machine doctor [main|wt1|wt2] [--check-only]
ds machine doctor --install-schedule [--every <minutes>]
Checks each of this machine's checkouts (all three by default) on five points, fixes what it may, and writes the results to the fleet registry:
| Point | Healthy when | Fixed by |
|---|---|---|
| freshness | A checkout parked at develop is at the latest develop |
Moving it to the latest develop. A checkout on a branch is never moved |
| install | Installed dependencies match the lockfile | pnpm install |
| data | The local database has every migration the code has, a demo-data checkout actually holds the Acme organization, and any customer copy is under 14 days old | Resetting demo (golden) data from the template, including a checkout whose database has no demo data yet; dropping an expired customer copy (below). Anything else is only reported |
| secrets | .env and the agent's credentials file came from the latest version of each bundle, and no .env still holds a copy of the agent's credentials |
Nothing: it tells you to run ds secrets pull, which rewrites every checkout's .env |
| tools | Node and pnpm match mise.toml |
Nothing: ds machine setup fixes it |
It also keeps the DevStride plugin current. A scheduled run, or one you start by hand, checks one machine-wide point, plugin: whether the main checkout's project-scope devstride plugin is the newest published release. When it is behind and the repository allows automatic updates (plugin.autoUpdate in .claude/ds-config.json, with no plugin.pin), it installs the newer release through the plugin's own verified updater and reads the install back. Sessions already running keep the copy they loaded until you type /reload-plugins or restart. A pinned install, automatic updates turned off, or --check-only is only reported, with the command to run. Right after it, a second point, codex plugin, brings Codex's copy of the plugin up to Claude Code's under the same rules, so a pin on Claude Code's copy holds Codex's too; restart running Codex sessions afterwards. The quick run inside ds pool checkout skips both points, and DEVSTRIDE_PLUGIN_UPDATE_CHECK=0 turns them off.
- Inside
ds pool checkoutit runs on the checkout you were just given, before its app starts, and fixes it for you. - Run by hand or on the schedule, it fixes only a checkout it can take over itself. It leaves alone the main checkout, a checkout on a branch, one with its app or another process running in it, and one someone holds. Those are only reported. It holds the checkout while it works and hands it back after.
- It never changes the main checkout's database, data it cannot identify, or a database ahead of the code. A customer copy is left alone too, with one exception: run unattended — on the schedule, or by hand without
--check-only— it drops a copy older than 14 days on a checkout nobody holds and resets that checkout to golden. Insideds pool checkoutit only reports such a copy, because the session that just took the checkout decides. Why: customer data should not sit on a laptop longer than the repro needs it. - If a run is stopped part-way it keeps the checkout held, because a reset can still be finishing inside Docker. The next scheduled run takes it back, first stopping any app the stopped run left running. To free it sooner, run the command the stopped run printed:
DEVSTRIDE_LEASE_TOKEN=<its holder> ds pool checkin <checkout> --session machine-doctor(the token is the doctor's lease holder, since a lease answers only to the session that took it).
| Flag | Description |
|---|---|
[checkout] |
main, wt1 or wt2. Default: all three |
--check-only |
Report everywhere and change no checkout. The fleet registry is still updated |
--install-schedule |
Run it on a schedule on this machine: launchd on macOS, systemd on Linux. It runs once straight away, and keeps the PATH, AWS profile and machine name of the shell that installed it. Log: ~/.devstride/logs/machine-doctor.log. Re-running replaces the schedule |
--every <minutes> |
With --install-schedule: how often, at least 15. Default: 60 |
ds machine ca-init#
ds machine ca-init [--mgmt-profile <profile>]
Creates the certificate authority, once for the whole company: a 10-year root certificate whose key and record go straight into the two management-account secrets. It refuses once the record exists, because every enrolled machine trusts the authority that is there. If it is interrupted after storing the key, running it again finishes from that key rather than making a new one.
ds machine provision#
ds machine provision --account <dev|prod> [--profile <profile>] [--mgmt-profile <profile>] [--confirm-production]
Creates the trust anchor, role and Roles Anywhere profile in one account, from a person's own admin session. The management session must also be valid, because the root certificate is read from its record. It describes what exists first and creates only what is missing. It refuses, and never overwrites, a trust anchor holding a different root certificate, a role that does not trust this anchor, or a profile set up differently: replacing any of those would lock out every enrolled machine. Commit the updated cli/commands/machine/trust-anchors.json afterwards so every machine can enroll.
| Flag | Description |
|---|---|
--account <dev|prod> |
Required. The account to provision |
--profile <profile> |
A person's own AWS profile for that account. For prod you can set DEVSTRIDE_PROD_PROFILE instead |
--mgmt-profile <profile> |
The management-account profile. Default: devstride-mgmt |
--confirm-production |
Required for prod |
ds machine enroll#
ds machine enroll <name> [--force]
ds machine enroll <name> --complete --cert-dev <file> --cert-prod <file>
Run on the agent machine, in two halves around ds machine sign. <name> is 2–41 lowercase letters, digits and hyphens.
- First run: makes one private key and one certificate request per account. Each key is a file only the machine's user can read (
0600, in a0700directory), under~/.devstride/machine-identity/<name>/, on every platform. It prints the exactsigncommands to run next.--forcereplaces the machine's existing identity. --complete: checks each signed certificate names this machine and account, and matches the key from step 1, then writes two AWS profiles:devstride-machine-<name>-devanddevstride-machine-<name>-prod. Pass absolute paths to--cert-devand--cert-prod. Add--forcewhen completing a--forcere-enrollment, which is how a machine renews its certificates before their year is up.
Then point this machine at it: export DEVSTRIDE_DEV_PROFILE=devstride-machine-<name>-dev. Every ./ds command and the session-start check pick it up with no other change. The plain aws and sst commands do not read that variable: pass --profile, or export AWS_PROFILE=$DEVSTRIDE_DEV_PROFILE. Production stays explicit (--profile devstride-machine-<name>-prod), as a person's production profile is.
Keys are files, never the macOS Keychain
AWS's credential helper can read a key from the macOS Keychain. The signatures it produces that way are rejected by Roles Anywhere ("Invalid signature"), and the Keychain asks for approval on use, which an unattended machine cannot give. So enrollment always uses key files.
ds machine sign#
ds machine sign <name> --account <dev|prod> --csr <path> [--out <path>] [--mgmt-profile <profile>]
Run on any machine signed in to the management account: issues one machine's certificate for one account. The certificate names the machine and account from these arguments, never from the request, so a request cannot claim another machine or account. Certificates last 365 days, so a lost machine lapses by itself. It is written to --out, or to <name>-<account>.crt.pem at the top of the checkout (./ds always runs from there, so pass absolute paths to --csr and --out), only after the record of it is saved. So nothing is ever issued that revoke cannot find. The signing machine needs OpenSSL 3 (brew install openssl@3), not macOS's built-in LibreSSL.
ds machine revoke#
ds machine revoke <name> [--confirm-production] [--dev-profile <profile>] [--prod-profile <profile>] [--mgmt-profile <profile>] [--take-over-lock]
Run from any machine signed in to the management account when a machine is lost, stolen or retired. It revokes every certificate the authority issued that machine, saves that, then uploads the revocation list to dev. --confirm-production uploads it to prod too. Without that flag, prod is reported as skipped and the command exits non-zero, because the machine is not yet shut off everywhere. It uses a person's own session per account (DEVSTRIDE_DEV_PROFILE / DEVSTRIDE_PROD_PROFILE, or the flags), and checks each profile reaches the right account first. If an upload fails, run the same command again: it refreshes the lists and changes nothing else.
Revoking stops the machine getting new credentials; a session it already holds stays valid until it expires, up to an hour. For a stolen machine, cut that short by revoking the role's active sessions in the IAM console.
Two revokes at once. A revocation list only ever moves forward: an account that already has an equal or newer list is not overwritten, but it is still switched on if someone switched it off. Only one revoke publishes at a time. A second one meanwhile stops with "another revoke (…) is publishing … — run this again in a minute", having changed nothing. A publication a stopped run left behind is never taken over automatically, because a stalled run could wake up and upload an older list. Once you know that run has stopped, run again with --take-over-lock.
ds machine issued#
ds machine issued [--mgmt-profile <profile>]
Prints every certificate the authority has issued, grouped by machine and account, as JSON: each with its serial, whether it is valid, expired or revoked, when it expires, and when it was revoked.
What a refused machine identity looks like
The
./dswrapper and the session-start check both say the machine identity was refused and never suggestaws sso login, because a login cannot fix a certificate. In order of likelihood: the machine was revoked, its certificate expired (re-enroll), or its key is gone.