Launch a device on AWS

If you don’t have a machine you want to leave running as a device, CodeHerder can launch one for you in your own AWS account. From Set up → Devices, click Launch on AWS: CodeHerder mints a registration token for you and opens AWS CloudFormation’s quick-create page with a CodeHerder device template already loaded and that token pre-filled. Pick your network settings, click Create stack, and AWS brings up an EC2 instance that connects back to CodeHerder on its own — no CLI install, no manual registration step.

The device runs in your own AWS account, so you pay AWS for the instance and its storage. It’s a good option when you don’t want to keep a laptop or workstation online just to run agent work.

Before you start

Have these ready:

• An AWS account you can create a CloudFormation stack in, plus a public subnet to launch into — its VPC is detected automatically, so that’s the only network setting you need to pick.
• A Claude subscription token. Run claude setup-token on any machine and paste the result into the stack form — this is what lets the device’s agents talk to Claude.
• A GitHub and/or GitLab token, if agents on this device need to push branches and open merge or pull requests. A token with write access to your repositories and permission to open merge/pull requests is enough; the form’s own field help explains what to paste. Leave a field blank to skip that host — one device can serve both GitHub and GitLab repositories at once if you fill in both.

Launch it

1. Go to Set up → Devices and click Launch on AWS.
2. AWS CloudFormation opens in a new tab with the CodeHerder template loaded, already in the right region.
3. Fill in the Agent credentials group (your Claude token, and a GitHub/GitLab token if you need one).
4. In Instance & network, pick a Public subnet. The other fields have sensible defaults — leave them as-is unless you have a reason to change them.
5. Click Create stack.

The registration token CodeHerder minted for you is only good for one hour. If you take longer than that to finish the form, the launch will fail to register — go back to the Devices page and click Launch on AWS again to get a fresh one.

If you plan to launch more than one device this way, give each stack its own stack name (the default is codeherder-device) — the name is what keeps each device’s credentials and storage separate.

What you get

• Spot pricing by default, in a single instance that relaunches automatically — falling back across several instance sizes to find capacity — if AWS reclaims it.
• A persistent data disk holding the device’s identity and its in-progress work, so a replacement instance comes back as the same device with its work intact, not a new one you have to reconnect.
• No inbound network ports. You reach the instance for a shell, if you ever need one, through AWS Systems Manager Session Manager rather than SSH.
• Everything preinstalled — the device already has the tools it needs to run agents and talk to your git hosts, so there’s nothing to install and no separate host-CLI login step.
• Credentials stored in AWS Secrets Manager, not on disk in plain text.

Attach it to your workspace

A device launched this way registers to your CodeHerder account, not to any workspace — it won’t show up in ch device list yet, because that only lists devices already linked to your active workspace. This is the most common point of confusion, so don’t skip it:

1. Wait for the instance to finish booting and connect — this happens automatically once the stack reaches CREATE_COMPLETE.
2. Go to Set up → Devices in the workspace you want it in, click Attach existing, and pick the new device from the list.
3. Alternatively, from the CLI: ch device link-workspace <deviceId> --workspace <workspaceId> — see Managing your devices for details.

Once it’s linked, assign and approve an agent to it the same way you would for any other device — see Agents and the CLI and Managing your devices. An AWS-launched instance registers under whatever hostname AWS assigned it, which usually isn’t memorable — give it a proper name so it’s easy to pick out of a list.

Change credentials or resize later

Open the stack’s Outputs tab in CloudFormation to find the AWS Secrets Manager secret backing the device. Update the credentials there, then terminate the EC2 instance — the device relaunches automatically and re-bootstraps with the new values. To change the instance size or other launch parameters, update the stack itself.

Remove it

Delete the CloudFormation stack to stop the instance and remove the AWS resources it created. Its data disk is deliberately kept behind (so you can recover it if you deleted the stack by mistake) — delete the volume yourself in the EC2 console once you’re sure you don’t need it, to stop paying for it. Also retire the device on the CodeHerder side — see Retiring a device.

If it doesn’t show up

• Check the stack’s Events tab in CloudFormation first — a failed launch (for example, a subnet that isn’t actually public) shows up there.
• Registration token expired — if you took longer than an hour to submit the form, go back to the Devices page and click Launch on AWS again for a fresh token.
• Needs attaching — a freshly launched device is unlinked to any workspace by design; see Attach it to your workspace above.
• Connected but not staffable — check the device’s health snapshot; see Device health and readiness checks.
• Need to look inside — open a shell on the instance from the EC2 console using Session Manager, no SSH key required.

Related guides

• How do I add a device? — the other way to add a device: run the device server yourself
• Managing your devices — day-to-day device health, concurrency, and linking devices to workspaces
• Connecting repositories — what a device needs to work on a given repository
• Understanding costs — how CodeHerder tracks model spend (AWS bills the instance separately, outside CodeHerder)