For admins: access, keys and stages
What an admin does so a developer can set up their machine: grant and remove GitHub and AWS access with one command, add the team's Seed and Neon keys, and look after each machine's AWS stage.
On this page
For admins: access, keys and stages#
On this page you, an admin, give a new developer everything they need before they paste the setup line, keep the team's shared keys in place, and look after the AWS stage every machine gets. The developer's side is Set up your machine.
What you need#
Run these from your own machine, set up with ./setup, in a terminal you are sitting at. An agent session can only preview them (--dry-run); the real run refuses, because it changes who can reach the company's code and AWS accounts.
- GitHub: your
ghsigned in as an admin of thedevstrideGitHub organisation. - AWS: a profile that reaches the management account, where IAM Identity Center lives. Setup writes it as
devstride-mgmtwhen your sign-in reaches that account (see Your AWS profiles).ds teamusesDEVSTRIDE_MGMT_PROFILE, elsedevstride-mgmt; pass--mgmt-profile <profile>to use another. If its sign-in has lapsed, the command says so: runaws sso login --profile <profile>and run it again. - DevStride: the agents' credentials file, which
ds secrets pull(and setup) writes. The command invites the person to the DevStride workspace with the agent key, which acts as the owner. Without the file it grants GitHub and AWS, prints a note, and invites them on the next run. - For the team's keys: access to the Neon and Seed organisation settings.
Give a developer access#
One command gives a new developer everything setup needs:
ds team add-developer --email jane.doe@devstride.com --github janedoe --name "Jane Doe" --dry-run
ds team add-developer --email jane.doe@devstride.com --github janedoe --name "Jane Doe"
Run it with --dry-run first: it checks everything and prints each change as would: ..., changing nothing. Then run it without. It is safe to run again: what is already in place prints as already: ..., and it only adds what is missing.
It does four things:
- GitHub: invites their GitHub login to
devstride/devstrideanddevstride/ds-docswith push access (no organisation membership). - AWS sign-in: creates an IAM Identity Center user with their work email as the sign-in name, and adds it to the group
devstride-developers. - The group's access: the first time, creates
devstride-developersand gives itAWSAdministratorAccesson the dev account only (809603945909). The permission setAWSAdministratorAccessmust already exist in Identity Center; the command never creates it, and stops naming it if it is missing. The group never reaches production. If the group has been given anything else by hand, the command refuses to add anyone to it until that is removed, so a new developer never inherits more than dev. - DevStride: invites their work email to the DevStride workspace, where the plans and tickets live. They get the workspace's default role; an invitation already sent is reported, never sent twice.
The email must end devstride.com or creativecapsule.com; --any-domain allows another.
Your one step in the AWS console#
AWS sends no password email to a user created this way unless Identity Center is set to. So, unless IAM Identity Center → Settings → Authentication → "Send email OTP for users created from API" is turned on (AWS then emails them a code at their first sign-in):
- Open IAM Identity Center → Users → their email.
- Choose Reset password, then Send an email to the user with instructions.
The command prints this step at the end of every real run (a --dry-run that still has changes to make stops before it).
What to send them#
The command also prints the steps to send the developer:
- Accept the GitHub invitations to
devstride/devstrideanddevstride/ds-docs(in their email, or at https://github.com/devstride/devstride/invitations). For an admin, the command prints the organisation invitation instead: https://github.com/orgs/devstride/invitation. - Open https://devstride.awsapps.com/start, sign in with their work email, and follow the code or link AWS emails them to set a password.
- Accept the DevStride workspace invitation (an email from DevStride), then sign in at https://app.devstride.com/devstride.
- On their Mac, follow Set up your machine.
They also need their own claude.ai and ChatGPT accounts, on plans that include Claude Code and Codex: those are theirs, never shared.
Add an admin#
An admin is someone who does what you do: grants access, signs and revokes agent machines, cuts releases and reads production. The same command gives them all of it:
ds team add-developer --email jane.doe@devstride.com --github janedoe --name "Jane Doe" --role admin --dry-run
ds team add-developer --email jane.doe@devstride.com --github janedoe --name "Jane Doe" --role admin
With --role admin it does, instead of the developer's grants:
- GitHub: invites their login to the
devstrideorganisation as an owner (an existing member is made an owner). An owner reaches every repository and can runds teamfor others. - AWS sign-in: creates their Identity Center user and adds it to the group
devstride-admins, which holdsAWSAdministratorAccesson the management, dev and production accounts (032309179398, 809603945909, 290560638399). The first run creates the group and gives it exactly those three grants; a group that has been given anything else by hand is refused, as the developers' group is. - DevStride: invites their work email to the workspace, like a developer. The Owner role can only be given to a membership that exists, so once they have accepted the invitation, run the same command again: it then makes them an Owner and reports everything else as
already. The command prints this as a note until it is done.
What they get next is the same as a developer, plus: their setup writes the devstride-mgmt and devstride-prod profiles beside the dev one, because their sign-in reaches those accounts (Your AWS profiles), and ds machine ready proves all three.
An admin reaches production and the management account from the first sign-in. Give the role to people you would trust with the production database, and remove it the day they leave: ds team remove-developer (below) takes back all of it in one run: their GitHub organisation ownership, their AWS sign-in and their DevStride membership.
The team's Seed and Neon keys#
Two shared keys live in the agents' bundle (devstride/dev/agent-env/agent-api-keys in the dev account's Secrets Manager), and every machine gets them with ds secrets pull, which setup runs:
| Key | What needs it | Where you make it |
|---|---|---|
NEON_API_KEY |
Every machine's AWS stage: setup's stage step makes each stage's database as a Neon branch with it, and ds neon runs with it. Without it, setup lists the stage under Needs you on every machine |
Neon → organisation settings → API keys (an organisation key) |
SEED_TOKEN |
Only ds seed deploy, a deliberate redeploy of a chosen commit. Deploys on merge need no key |
Seed → organisation settings |
Add or replace one from your own machine, with the value on your clipboard, never on the command line:
pbpaste | ds secrets set agent NEON_API_KEY
ds secrets pull
Each machine picks it up on its next ds secrets pull (or ./setup). Both keys reach production today (owner decision, 2026-10-05), so treat them like production credentials. How to rotate them, and every other key's owner, is in Credentials and access.
Each machine's AWS stage#
Every machine setup runs on gets its own AWS stage in the dev account, named after the machine. Setup builds it once (about 30–40 minutes, unattended), and records it in that machine's secrets bundle (devstride/dev/agent-env/machine/<machine>). ds fleet status shows each machine's stage in its STAGE column, but only for machines that report to it: a machine appears once the health check (ds machine doctor) has run there, which is hourly on an agent machine (or a person's machine set up with ./setup --timer) and otherwise only when someone runs ds pool checkout on it. A person's own Mac can therefore be missing, or listed with an old date, while its stage is in daily use. A stage is named after its machine, so before removing a stage you cannot match to a machine there, ask the person whose machine it is named after.
What a stage costs while idle is close to nothing:
- about 38 CloudFormation stacks of serverless resources (Lambda, queues, an API), billed only when used;
- a Neon database branch (
stage-<stage>, made fromgolden-data) with a small compute (0.25 CU) that suspends after five minutes without queries, so it costs only while someone uses the stage; - its own domain name and certificate (
api-<stage>.devstride.dev).
The hourly health check on agent machines reads the stage's records and stacks, never its database, so it does not keep the database awake.
Retire a machine#
When a machine is wiped, lost, handed on or simply no longer used, remove its stage from any machine signed in to the dev account that has the team's Neon key, in a terminal you are sitting at (an agent session cannot):
ds stage remove --machine <its name> --dry-run # what it would delete
ds stage remove --machine <its name> # you retype the stage name to confirm
It deletes the stage's stacks, its config, its Neon branch, and the stage's keys in that machine's bundle, and schedules the stage's signing key in AWS for deletion (AWS keeps it 30 days, restorable until then). It is permanent: the stage's data and its sign-in users go with it. If the same Mac is wiped and set up again under the same name, setup builds it a fresh stage. If it was not wiped, it still holds its own record of the old stage (.ds/stage-create.json in its main checkout), and setup would skip the new stage's migrations and demo logins: on that Mac, run ds stage remove there instead, or delete that file before running ./setup.
For an agent machine, also shut off its AWS identity, from a machine signed in to the management account with your own dev and production sign-ins:
ds machine revoke <its name> --confirm-production
The machine then gets no new AWS sessions; one it already holds ends within an hour. Every key it pulled before stays valid until rotated, so a lost machine also means rotating the shared keys: see A revoked machine still holds what it pulled.
Remove a developer#
ds team remove-developer --email jane.doe@devstride.com --github janedoe --dry-run
ds team remove-developer --email jane.doe@devstride.com --github janedoe
It takes back everything add-developer gave them:
- GitHub. A member of the
devstrideorganisation (every admin is an owner there) is removed from it, which takes every repository with it. Anyone else loses their push access to both repositories, and any pending invitation, to a repository or to the organisation, is cancelled. Without--github, GitHub is left alone. - AWS. Their sign-in comes out of
devstride-developersanddevstride-adminsand is deleted. - DevStride. Their workspace membership is removed, or their invitation withdrawn if they never accepted it.
The dry run lists each step. You retype their email to confirm; it cannot be undone. If your machine has no agent key (ds secrets pull writes it), the DevStride step is skipped and the command tells you to remove them under Settings → Users instead.
It refuses, and you finish by hand, when:
- their AWS sign-in has more access than the two groups (another group, or a direct assignment): deleting it would remove that too;
- you name yourself.
Then finish offboarding:
- Find their machines:
ds fleet statuslists the ones that report to it, but a person's own Mac may be missing (see Each machine's AWS stage), so ask them too. For each, retire it as above:ds stage remove --machine <name>, and for an agent machineds machine revoke <name> --confirm-production. - Their machines pulled the team's shared keys, including the agents' bundle. Rotate the ones you would not want a former team member to hold: see Rotating a shared key.
- Their claude.ai and ChatGPT accounts are their own; nothing to do there.
Canary accounts#
The accounts the agents and release checks sign in with are meant to be registered to DevStride's shared canary identity, not to you; a few are still tied to the owner, as Canary accounts marks. When you create or change one (a new service login, a rotated key, a renamed app), follow that page's rules and update the repository's inventory, docs/canary-accounts.md, in the same change.
Agent machines#
An agent machine (one that runs Claude Code with nobody at the keyboard) gets its own AWS identity rather than a person's sign-in. Its setup needs one approval from someone who can sign with the management account, usually you, sitting at the machine while ./setup --agent <name> runs. Agent machines covers the run, the yearly renewal (ds machine enroll <name> --force, then ./setup --agent <name>) and, when you cannot be at the machine, the route where you sign its requests on your own machine.
Next: back to the Overview