On this page

Set up your machine#

On this page you take a Mac with nothing on it to a working DevStride machine. You paste one line into Terminal; setup installs and configures the rest, stops only when it needs you, builds your machine its own AWS stage, and finishes by proving the machine works with the word READY. The same page covers an agent machine (one that runs Claude Code with nobody at the keyboard): the differences are under Agent machines.

Before you start#

Have these ready:

  • A Mac with 16 GB of memory and about 80 GB free, Apple silicon or Intel. Setup checks that Docker (Docker Desktop, or OrbStack or Colima if you already use one) has at least 4 CPUs and 8 GB of memory, which the test suite needs, and stops until you raise them in its settings; an 8 GB Mac cannot pass. Docker Desktop's own default is often far less than the Mac can spare (about 8 GB, even on a 64 GB Mac), so on a Mac with 32 GB or more setup also asks for half the Mac's memory, up to 24 GB, which the three checkouts and the demo-data build need together. That one is a step for you: setup names the number and where to set it (Docker Desktop's Settings → Resources, then Apply), and never changes the setting itself, because Docker restarts to apply it and that stops every container on the Mac. Each checkout's app also needs about 3 GB of Docker's memory free when it starts: with less, setup holds that start and says how much is free, rather than start it and crash Docker with every container on the Mac (see Troubleshooting). Nothing checks the disk: the figure is what a machine in daily use holds (the three checkouts' dependencies, about 12 GB; the Docker images, volumes and build cache, about 50 GB; the demo data).
  • An administrator account on the Mac. Homebrew's installer and Docker's installer ask for its password.
  • Your GitHub, AWS and DevStride access. An admin gives you all three with one command (see For admins). You then:
    • accept the GitHub invitations: to devstride/devstride (the product) and devstride/ds-docs (these docs, which setup clones beside it), or, for an admin, to the devstride organisation;
    • set your AWS password: sign in at https://devstride.awsapps.com/start with your work email, and follow the code or link AWS emails you. If nothing arrives, ask the admin: their command printed the one step that sends it;
    • accept the DevStride workspace invitation (an email from DevStride), then sign in at https://app.devstride.com/devstride. That is where the plans and tickets the rest of this guide sends you to live.
  • Accounts for the two coding agents. A claude.ai account on a plan that includes Claude Code (Pro or above): setup signs Claude Code in with it and accepts nothing else (not an API key). And a ChatGPT account on a plan that includes Codex (Plus or above): setup signs Codex in with it. A free account of either cannot sign the agent in.

1. Paste the one line#

Open Terminal and paste this line, all of it:

{ command -v brew >/dev/null || [ -x /opt/homebrew/bin/brew ] || [ -x /usr/local/bin/brew ] || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"; } && eval "$(command -v brew >/dev/null && brew shellenv || /opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv)" && { command -v gh >/dev/null || brew install gh; } && { gh auth status -h github.com >/dev/null 2>&1 || gh auth login -h github.com -p https -w; } && { [ -d ~/dev/devstride/.git ] || gh repo clone devstride/devstride ~/dev/devstride || { echo "Could not clone devstride/devstride (gh says why above). If gh could not find the repository, your GitHub access is not in place yet: ask an admin to run ds team add-developer for you, accept the invitation, then paste this line again."; false; }; } && cd ~/dev/devstride && { [ -f setup ] || { echo "~/dev/devstride is older than ./setup: run git switch develop && git pull in it, then paste this line again."; false; }; } && ./setup

It does five things, skipping any that are already done:

  1. installs Homebrew, the Mac's package manager (its installer asks you to press Return and for your Mac password, which shows no characters as you type, and adds Apple's command line tools and git on the way);
  2. installs the GitHub CLI;
  3. signs you in to GitHub in the browser;
  4. clones the repository to ~/dev/devstride;
  5. runs ./setup.

Pasting it again on a machine that has some or all of this just carries on, and an existing clone keeps its branch and your changes: the line never pulls. So a clone made before ./setup existed (October 2026) has no setup in it, and the line stops and says so: run git switch develop && git pull in ~/dev/devstride, then paste it again. If it stops with "Could not clone devstride/devstride", read gh's message above it: when gh could not find the repository, your access has not been granted or accepted (see Before you start); when it says the folder already exists, ~/dev/devstride is there but is not a clone, so move it aside.

Already cloned it somewhere else? The line always uses ~/dev/devstride, so it would make a second clone. Instead, update your clone and run setup from inside it: cd <your clone> && git switch develop && git pull && ./setup. Setup works from any folder; ./setup only has to be run from inside the clone, or it is "not found" (see Troubleshooting). Run it in the clone itself, never in one of its worktrees (such as .worktrees/wt1, or a worktree you made yourself): setup refuses there and names the clone to run it in (see Troubleshooting).

For an agent machine, choose 2) An agent machine that runs unattended at setup's first question, or run ./setup --agent <name> (see Agent machines).

2. Answer the first questions#

./setup first installs what it needs to run at all: Node and pnpm at the versions the repository pins (with mise, a tool that installs exact versions, unless the right ones are already on your Mac; see Which Node your terminal runs afterwards) and the repository's dependencies. Then it asks a few questions, each remembered for later runs:

  • whether this is your own machine, an agent machine, or both. At a terminal this is a short screen with three numbered choices, 1) My own machine, 2) An agent machine that runs unattended and 3) Both, each with what it sets up; type the number and press Enter. Enter alone takes your own machine, or, on a machine that is already enrolled as an agent, that agent, which the screen names. Both means an agent machine you also work at: it is set up as that agent in full (its certificate identity, Docker at login, staying awake, the hourly check, the agents' settings) and also gets your own apps; ./setup --agent <name> --own says the same without asking. An answer setup does not understand is asked again. A machine an earlier run recorded as your own keeps that record: delete ~/.devstride/machine.json to answer again;
  • this machine's name (press Enter to keep the one shown, or type another: 2 to 41 lowercase letters, digits and hyphens). It also becomes the name of your AWS stage, so it cannot be dev, prod or staging, or contain aws, amazon or cognito anywhere (AWS refuses those in the stage's sign-in address). Watch for a name made from your Mac's: dawsons-macbook-pro contains aws. An agent machine is named after its enrolled identity, and another name is refused;
  • when git has none yet, your name and email for commits (GitHub's are offered; press Enter to take them).

3. Read the plan, then say yes once#

Setup lists every change it would make, stage by stage, then the moments it will wait for you, then the changes to what your agents may do. On a Mac that has been set up before, or already has some of the tools, the list starts with what it found Already in place now (checked again when the run reaches it): an AWS stage that is already built, for example, is listed there rather than offered for another 30–40 minute build. When setup is going to take an old alias ds='./ds' line out of your shell's startup file, the plan names the file and the line numbers.

On a blank Mac the list is long; its last part reads roughly like this:

It stops and waits for you at:
  containers: install Docker Desktop and run its installer (accepts Docker's licence) — asks for your Mac password
  containers: wait for you to give Docker Desktop at least 4 CPUs and 8 GB of memory, if it has less (on a Mac with 32 GB or more, half the Mac's memory, up to 24 GB)
  agents: sign in to Claude Code in the browser
  agents: sign in to Codex in the browser
  aws: sign in to AWS once in the browser
  machine: wait for you to sign in to GitHub when the GitHub CLI is signed out (gh auth login)
Then it proves the machine works:
  proof: ...
Answering y also allows these changes to what your agents may do (--yes never does):
  agents: Setup is about to make /Users/jane/dev/devstride a trusted Codex project and approve its committed hooks, ...
  plugin: Setup is about to change what Claude Code may do on this machine without asking you: ...
  plugin: Setup is about to mark /Users/jane/dev/devstride trusted in Claude Code: ...
  plugin: Setup is about to make /Users/jane/dev/devstride/.worktrees/wt1 a trusted Codex project ...
  plugin: Setup is about to make /Users/jane/dev/devstride/.worktrees/wt2 a trusted Codex project ...
Nothing that is already right is touched, and running this again is safe.

Below it, setup shows the plan as one short screen: how many steps fall under each heading, the changes to what your agents may do in full, and four choices:

── Plan ────────────────────────────────────────────────────────────────
This run changes this machine only where something is missing: 31
It stops and waits for you at: 6
Then it proves the machine works: 1

Answering y also allows these changes to what your agents may do (--yes never does):
  agents: Setup is about to make /Users/jane/dev/devstride a trusted Codex project and approve its committed hooks, ...
  ...

  y) Proceed — make the changes above, waiting for you where a step needs you
  n) Stop — change nothing; run ./setup again any time
  d) Show every line — print the whole plan, then ask again
  s) Skip a stage — name a later stage to leave alone this run, then ask again

Choose [n]:

Type y and press Enter. That one answer covers everything listed, including the three changes to what your agents may do:

  • Claude Code's permission settings: every rule setup adds is printed, so you can read what Claude Code may then do here without asking you.
  • Claude Code trusting this repository, so its committed settings and hooks apply in all three checkouts without a first-session prompt.
  • Codex's approval of the repository's hooks, in each of the three checkouts: the three hooks Codex lists on its own /hooks screen, which are the AWS check at session start, the merge guard's banner at session start, and the merge guard's check before each shell command (the merge guard stops a push straight to develop or master). Setup records the approval exactly as Codex's /hooks screen would, and lists the commands Codex will then run.

Pressing Enter alone means Stop: setup then only reports and changes nothing. Only a typed y goes ahead. d prints every line of the plan again, and s asks which later stage to leave alone this run (the same as --skip), then shows the screen again. ./setup --yes answers the plan for you but never allows those three changes, and setup never makes them when an agent ran it: it then says, under Needs you, that only a person who runs ./setup at their own terminal and types y can.

4. The moments it waits for you#

Setup stops at each of these, says exactly what to do, and carries on by itself once you have done it. Each one is a short screen headed with what it is waiting for and how many times this run has needed you so far (needs you, 2), with its choices and what each does: usually Enter when it is done (or to check again), r to run a sign-in again, and s to skip it for now.

  • Your Mac password, for Docker's installer. Installing Docker Desktop runs Docker's own installer, which accepts Docker's licence for you and sets up its helper. Setup forgets the password straight after.
  • Docker's first start. If Docker Desktop shows a window when it first starts (a welcome screen, a sign-in offer), finish or close it; signing in to Docker is not needed.
  • Browser sign-ins: Claude Code (with your claude.ai account), Codex (with your ChatGPT account), AWS (once, with the sign-in your admin created; if the AWS page does not recognise your work email, your access has not been set up yet: see AWS does not recognise your work email), and GitHub again only if the GitHub CLI has been signed out. Each opens a browser window; approve the sign-in there. For Codex, AWS and GitHub, where no browser can open, setup shows a link and a code instead. If Claude Code is already signed in with an API key, setup lists it under Needs you: run claude auth logout, then claude auth login --claudeai, then ./setup again.

If Codex still does not run the repository's hooks after setup recorded the approval (because a new Codex release changed its record, say), setup opens Codex for you to approve them by hand once: type /hooks, approve the three project hooks setup names (the AWS check at session start, the merge guard's banner at session start and the merge guard's check before each shell command), then type /quit.

If setup finds that your AWS profile cannot be used for the dev account because of a DEVSTRIDE_DEV_PROFILE line in your shell's startup file, it names the file and line and offers to change that line to devstride-dev for you (keeping a copy of the file), or to leave the AWS steps for now; Enter leaves them. See Troubleshooting.

Every question and sign-in comes before the last stages. Once the demo data starts building, setup needs nobody: the demo data takes a few minutes, and your AWS stage after it about half an hour more. A good moment to get a coffee.

For a sign-in or an installer, setup runs it first and, if it did not finish, offers s to skip it for now. Setup then finishes everything that does not depend on that step and lists what is left. Ctrl-C stops setup at any point. Either way, run ./setup again later: it picks up from where it stopped.

What setup installs#

You install none of this by hand:

  • Tools, from the repository's Brewfile: the AWS CLI, the GitHub CLI, git, jq, Neon's command-line tool, OpenSSL 3, psql (PostgreSQL 15's client, linked onto your PATH only when you have no psql already) and poppler (which turns PDF pages into images, for the agents). AWS's credential helper, which has no Homebrew package, is downloaded from AWS into ~/.local/bin and its checksum checked. Node and pnpm at the versions the repository pins, unless the right ones are already there.
  • Docker Desktop, started and checked for enough CPUs and memory. On a Mac that has OrbStack or Colima, the plan names that runtime instead of announcing a Docker Desktop install: setup starts it when it is not running, and installs nothing; when it has too few CPUs or too little memory, setup says where to raise them in that runtime.
  • Claude Code and Codex, signed in, with the DevStride plugin (the /devstride:* commands), the connection to DevStride and the settings both agents need here. When the plugin is older than the repository needs, setup updates it with the plugin's own updater, which checks the installed files against the published release, and then brings Codex's copy of the plugin up to Claude Code's, so the two agents run the same version. On a Mac, Codex is Homebrew's cask, which setup installs on every machine (a Codex installed with npm that would shadow it is removed; your own install elsewhere is kept and named). Upgrading it when Homebrew has a newer one is a separate step, Codex current, which nothing else waits on.
  • Google Chrome, with the Claude in Chrome extension waiting to be enabled. Agents do their browser work through it (see After setup). If your Mac will not let setup offer the extension, the run still finishes: setup lists it under When you can with the likely causes and the Chrome Web Store link to install it yourself (see Troubleshooting).
  • On your own Mac, or a "both" machine: the Claude and ChatGPT desktop apps, iTerm2 and Oh My Zsh (see Your own tools).

It then:

  • makes the two extra checkouts, ~/dev/devstride/.worktrees/wt1 and wt2 (agents work there; the clone itself is the main checkout, where you work), with their dependencies and their own generated types;
  • writes each checkout's .env from the team's secrets (see Credentials and access);
  • starts the main checkout's app in Docker, and fills all three checkouts with the demo data;
  • builds this machine's own AWS stage (see Your AWS stage);
  • adds a marked block to your shell's startup files, and puts ds on your PATH (~/.local/bin/ds runs the ds of whichever DevStride checkout you are in, so run it from inside one: anywhere else it says ds: run this inside a DevStride checkout);
  • clones the docs site to ~/dev/ds-docs.

Which Node your terminal runs afterwards#

The repository needs Node 22 and the pnpm it pins (see mise.toml). What happens to your terminal depends on what it runs today:

  • Already a Node 22 and that pnpm (from nvm, fnm, Homebrew or anything else): setup uses them and your terminal keeps them. They stay first for the whole run, even when Homebrew brings in a newer Node of its own part-way through (Neon's command-line tool depends on one), and even when that other Node was already ahead of yours: setup says so (Homebrew's node v26… is ahead of your Node 22 (…): using yours for this run) and does not install mise as a third Node.
  • Anything else (another Node version, another pnpm, or none): setup installs the pinned Node 22 and pnpm with mise, and its shell block makes every new terminal start on them, in every folder. If other projects need another Node, switch in that terminal with your version manager, or set your version manager's default to Node 22 and the pinned pnpm before running setup so nothing changes.

After writing the block, setup opens a fresh login shell and checks which Node and pnpm it finds. If a new terminal would run anything other than what it ran before or what setup installed, setup takes its block back out and tells you. Your startup files are then exactly as they were. Setup keeps a copy of each startup file it changed, ending .before-devstride-setup. See Troubleshooting.

5. When it finishes#

Setup ends by listing what it changed and, when anything is left, up to three lists:

  • Needs you: a step only you can do, with the command to do it.
  • Waiting on the above: steps that wait for one of those.
  • When you can (nothing waits on these): notes that never stop the machine being ready, such as enabling Claude in Chrome.

Open a new terminal now, and cd ~/dev/devstride. ds and the pinned Node come from the startup block setup just added, so only a new terminal finds them: in the terminal setup ran in, even ./ds can fail with node: command not found on a new Mac. ds runs from inside a checkout. Setup writes that block for zsh and bash; for any other shell it prints the lines to add yourself.

READY#

Setup's last stage proves the machine works: ds machine ready. It ends with one word. READY means no proof failed. Check again at any time:

ds machine ready           # the full proof: a few minutes, it starts apps and runs a landing check
ds machine ready --quick   # in seconds: no app started, no model called (what the hourly check runs)

A quick proof right after setup looks like this (shortened):

Proving this machine (jane-mac, a person's own machine) — quick: no app started, no model called:
  pass  tools: node, pnpm, git, gh, aws, jq, neonctl, OpenSSL 3, psql, pdftoppm, docker, claude, codex, python3
  pass  aws: dev account, secrets
  pass  github: your sign-in
  pass  devstride: agent key, Claude Code's connection, Codex's connection
  pass  checkouts: main dependencies, main demo data, main database, wt1 ..., wt2 ...
  pass  stage: recorded, stacks, config, database
  pass  claude: signed in, plugin, settings, trusts this repository, hooks, guard refuses a push to develop, ...
  pass  codex: installed, signed in, reads all of AGENTS.md, review engine settings, plugin
  pass  machine: git identity, shell startup files, ds from anywhere, docs repository
  pass  credentials: main .env, wt1 .env, wt2 .env, agent file
READY

Each line is one of:

  • pass: proven.
  • FAIL: not working, with the fix on the same line. Any FAIL makes the verdict NOT READY, followed by how many proofs failed and each failure 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; the line says which, and you run the proof again when the checkout is free or memory is.
  • you: a step only you can take, for example Claude Code's settings when an agent ran setup.
  • note: something to do when you can. Never a failure.

The full proof also signs in to each checkout's app as the demo user (main's app must already be running; wt1's and wt2's are started and stopped in turn), runs the landing check (the same check every change runs before it lands) in a free checkout, and has Codex prove the merge guard in each checkout and answer one line through the review command.

Run ds machine ready from inside a checkout, like every ds command.

After setup#

A few things only you can do, once:

  • Enable Claude in Chrome. Open Chrome. It offers the Claude extension: click Enable, then sign in to Claude in it. Until you do, setup reminds you under When you can.
  • Sign in to the desktop apps (your own Mac): open Claude and ChatGPT from Applications and sign in.
  • Open the app. The main checkout's app is running at http://localhost:8080. Sign in with a demo login: acme.devstride, password Demo@123 (a username, not an email). After a restart, start Docker Desktop, then run cd ~/dev/devstride && ds worktree up main. Local Development explains the local stack.

Keeping the machine current#

Three tools keep a machine up to date, each with its own scope:

Tool Scope When you use it
The devstride plugin's /devstride:doctor and /devstride:update The general setup every repository that uses the delivery loop shares When a session says the plugin is behind, or the loop behaves oddly
./setup This application's machine setup Any time: it installs what is missing and brings the machine current (see Running it again)
Asking an agent to "update my environment" The between-sessions refresh (the repository's ds-update-local-env skill) After a break, or before a run of work

The between-sessions refresh runs ./setup --yes, then the two refreshes setup leaves alone: it rebuilds the demo-data snapshot and copies it into every checkout, and brings your AWS stage's demo logins and dates current (ds stage create --member wt2 --refresh). It then proves the machine with ds machine ready. It asks you once for the whole refresh, and stops only for a sign-in or a step only you can take. In between, the hourly check (on an agent machine, or one set up with --timer) keeps the plugin, Codex's copy of it and the free checkouts current.

Your AWS stage#

Every machine gets its own AWS stage: a full copy of DevStride in the dev account, named after the machine, that you and your agents can deploy to and test against without touching anyone else's. Setup's stage step builds it once the demo data is in place, in about 30–40 minutes, unattended:

  • a copy of the demo data on its own Neon database branch (stage-<stage>, made from the team's golden-data branch);
  • the stage's config and its first deploy;
  • the database migrations, the demo logins (acme.devstride and the others, password Demo@123) and today's dates.

Its name and database are recorded in your machine's secrets bundle, so every checkout's .env knows them. After that, setup checks the stage on each run. It finishes or repairs it when its config or stacks are missing or unfinished, and when the stage's database is behind develop's migrations, it refreshes the stage in a free wt1 or wt2 (see Bringing the stage current).

To run a checkout against your stage instead of Docker, from inside ~/dev/devstride:

export DEVSTRIDE_SESSION=<your name>
ds pool checkout wt1 --mode cloud --purpose "<what you are doing>"   # take wt1 and run its own code against your stage (the backend in live mode, and the UI); export the token it prints as DEVSTRIDE_LEASE_TOKEN
ds pool cloud wt1 --off    # back to Docker
ds pool checkin wt1        # hand wt1 back when you are done

(ds pool cloud wt1 switches a checkout you already hold.)

One checkout per machine can run against the stage at a time. The Develop page explains the checkout pool and its leases.

Before it starts anything, ds pool cloud compares the stage's database with that checkout's code. When the checkout has migrations the database lacks, it applies them first and checks each one landed, then binds. When the database is ahead of the checkout's code, it refuses and changes nothing, because nothing moves a database backwards: bring the checkout up to date (pull, or rebase onto develop), then bind again.

Bringing the stage current#

Your stage does not follow develop by itself. When its database falls behind develop's migrations, ./setup notices and refreshes it; ds machine ready notes it too. To refresh it yourself, hold wt1 or wt2 (clean) and run:

export DEVSTRIDE_SESSION=<your name>
ds pool checkout wt2 --purpose "stage refresh"   # in a plain terminal, run the export DEVSTRIDE_LEASE_TOKEN=… line it prints
ds stage create --member wt2 --refresh
ds pool checkin wt2

A refresh starts sst dev once from that checkout, which deploys whatever stacks changed since (and nothing when none did), then applies new migrations, re-creates the demo logins, moves the demo dates to today, and stops sst dev. It never runs sst deploy. Run it with the checkout at the code you want on the stage: usually develop.

Two more things you may need:

  • Stripe. Your stage uses the team's test-mode keys, but needs its own webhook. In the Stripe test dashboard, add the endpoint https://api-<stage>.devstride.dev/v1/subscriptions/stripe/webhooks, listening to charge.refunded, charge.refund.updated and refund.updated on your account. Store its signing secret in your machine bundle, then push it to the stage, from inside ~/dev/devstride:

    pbpaste | ds secrets set machine STRIPE_WEBHOOK_SECRET
    ds secrets pull
    DEVSTRIDE_STAGE=<stage> DEVSTRIDE_REGION=us-east-1 ./ds -b script set-config
    

    The last command matters: the stage reads its secrets from its own config, which setup wrote once when it built the stage. Without it, every webhook from your endpoint is rejected.

  • Removing it. ds stage remove --dry-run shows what removing your stage would delete; without --dry-run you retype the stage name to confirm. It is permanent: the stage's data and sign-in users go with it. Running ./setup again builds a fresh one.

The stage needs the team's Neon key on your machine. If setup lists the stage under Needs you, see Troubleshooting.

Running it again#

Run ./setup whenever you like; every step checks before it changes anything. It is also how a machine stays current. Each run:

  • first brings the main checkout up to the latest develop, so setup runs today's code, but only when nothing would be lost: the clone is on develop (or detached on it), with no commits or changes of its own. It asks once (this clone is 12 commits behind develop. Bring it up to date before setting up? [y/N]), or does it without asking under --yes. Otherwise it says why in one line (this clone is on <branch>, not develop, or has changes of its own (<file>)) and carries on with the code the clone has;
  • updates the devstride plugin when it is older than the repository needs, and brings Codex's copy of it up to Claude Code's;
  • upgrades Codex when Homebrew has a newer one;
  • pulls newer secrets, applies new migrations to the main checkout's database, and refreshes your AWS stage when its database is behind.

On a machine that is already current it changes nothing, still runs the proof, and ends with Nothing to change. (or the items that need you). Restart open Claude Code and Codex sessions after a plugin update: a running session keeps the copy it loaded. ./setup --dry-run only reports, and never fetches or moves the clone. ./setup --skip <stages> leaves stages alone (for example --skip stage to leave your AWS stage for another day). Setup treats a skipped stage as already done, so a later step that relies on it still runs, and reports what it could not do. ./ds machine setup --help lists every option, and the command reference lists the eleven stages.

Setup's own log is .ds/machine-setup.log in the main checkout (the clone itself); the demo-data build writes to .ds/machine-setup-data.log, the stage's first deploy to .ds/stage-deploy.log in the checkout it deployed from, and the full proof to .ds/machine-ready.log.

Agent machines#

./setup --agent <name> sets up a machine that will then run Claude Code sessions with nobody at the keyboard (add --own when you work at it too: it then also gets your own apps). You sit at it while setup runs. The name you give it (2 to 41 lowercase letters, digits and hyphens, for example m5-philreynolds) becomes its AWS identity, its own secrets bundle, its AWS stage and its row in ds fleet status. Never reuse a name another machine has had.

What setup does differently:

  • One AWS approval, then its own identity. Setup asks you to approve one AWS sign-in in the browser, and uses it to issue the machine its own certificates for the dev and production accounts. AWS exchanges those for short sessions named after the machine, so no person needs to sign in again until the certificates are renewed, once a year. Setup then removes that sign-in. The approval must come from someone who can sign with the management account (an administrator); without that access, setup names the other route: an administrator signs the machine's two requests on their own machine, and you save the two certificates where setup says and run it again (the administrator route has the steps).
  • No changes to what the agents may do. Setup never writes Claude Code's settings, trust or Codex's hook approval on an agent's behalf: the first person to run ./setup at that machine's own terminal and type y does.
  • It stays awake on mains power: setup asks for your Mac password once more to set this.
  • Docker Desktop starts by itself whenever you sign in to the Mac.
  • An hourly health check (ds machine doctor) keeps the idle checkouts current and reports every checkout's health to ds fleet status. It runs as a launchd job (launchctl print gui/$UID/com.devstride.machine-doctor shows it) and logs to ~/.devstride/logs/machine-doctor.log.
  • FileVault and automatic login: setup reports both and changes neither. With FileVault on, the machine's disk (and its keys, which reach production) stays encrypted if it is lost, but after a restart it waits at the unlock screen until someone signs in. To have it sign in by itself after a restart, turn FileVault off and turn on automatic login (System Settings → Users & Groups); only choose that for a machine kept somewhere physically secure.

Browser sign-ins are yours to do once. A few sites have no key an agent can hold: the Seed and Neon consoles, Stripe, Intuit, Azure and the DevStride app. On each agent machine, add a Chrome profile named DevStride Agent in the same macOS user the agent runs as, enable Claude in Chrome there, and sign that profile in to each site once. Agents then work there and never type a password. Nothing can check a browser's sign-ins, so the READY report lists them as a reminder.

Renewing (yearly, or to replace a machine's identity): ds machine enroll <name> --force, then ./setup --agent <name>, which signs and installs the new certificates from one approval. The first command removes the old certificates at once, so the machine has no AWS access until setup finishes: do it while no session needs AWS. When replacing an identity rather than renewing it, also revoke the old certificates (Retire a machine has the command).

Retiring or losing a machine is an admin's job: see For admins.

Your own tools#

On your own Mac, or on an agent machine you also work at (Both), setup also installs these, so every developer starts from the same place:

  • The Claude and ChatGPT desktop apps, from Homebrew.
  • iTerm2, a terminal app, from Homebrew. Open it from Applications or Spotlight and use it instead of Terminal.
  • Oh My Zsh, which gives zsh its prompt, themes and plugins, with its own installer. On a new Mac, setup starts ~/.zshrc from Oh My Zsh's template (the robbyrussell theme and the git plugin) and keeps its own startup block after it. To change the theme or the plugins, edit ZSH_THEME and plugins in ~/.zshrc, outside setup's marked lines.

If your ~/.zshrc already has lines of your own, setup never replaces it with Oh My Zsh's template (it only adds its own marked block, as on every Mac). It installs Oh My Zsh in ~/.oh-my-zsh and, at the end of that run, lists under When you can the four lines that turn it on. If your shell is not zsh, setup leaves Oh My Zsh out. Setup looks for all of these on every run, so it installs any one again if it has been removed.

Linux#

./setup runs on Linux too, but only the Mac route has been tried end to end. It needs Homebrew (it installs it only when Node or pnpm is missing too) and python3, and lists what it cannot install with the command to run yourself: Docker Engine (and adding yourself to the docker group) and Codex (npm install -g @openai/codex). Chrome, the desktop apps, iTerm2, Oh My Zsh and keeping the machine awake are Mac-only; the hourly check runs as a systemd timer. If Node and pnpm are already installed and Homebrew is not, setup's tools step stops and asks you to install Homebrew first.

Trying it on a blank Mac#

Before a change to setup is released, someone runs it on a Mac that has never had DevStride on it: a new Mac, or one erased (a new user account is not enough, because Homebrew and Docker are installed for the whole Mac). Paste the line above with one change, so it clones the branch being tested: replace gh repo clone devstride/devstride ~/dev/devstride in it with gh repo clone devstride/devstride ~/dev/devstride -- --branch <the branch>.

When a step fails, send back the line setup printed for that step, .ds/machine-setup.log, and for the demo data .ds/machine-setup-data.log. Every place this page and the Mac disagree is a bug in one of them. The repository's setup rehearsal proves setup's order and waits on every change, with stand-ins for every outside program; only a real blank Mac proves Homebrew's and Docker's own installers.

If something goes wrong, see Troubleshooting.

Next: Credentials and access

Powered by DevStride