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. It also lands already joined to the workspace you launched it from, ready to use as soon as it connects.

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.

Which template loads

CodeHerder’s hosted service loads the template that CodeHerder publishes. A self-hosted install loads the template its administrator set. See Pin the AWS device template.

Before you start

Have these ready:

Workspace owner or admin. The Launch on AWS button is visible to everyone, but starting a launch needs one of those two roles — a member who clicks it gets an error and nothing launches. If that’s you, ask an owner or admin to launch it instead.
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

Go to Set up → Devices and click Launch on AWS.
AWS CloudFormation opens in a new tab with the CodeHerder template loaded, already in the right region.
Fill in the Agent credentials group (your Claude token, and a GitHub/GitLab token if you need one).
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; the default instance size is a good balance for most repositories, but a memory-heavier size is worth picking for a large one.
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 instance families at the size you picked to find capacity — if AWS reclaims it.
A persistent data disk holding the device’s identity and its worktrees, so a replacement instance comes back as the same device, 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.
Self-healing by default. If the device process wedges while the instance keeps running, the stack notices and replaces it automatically, no action needed from you. This is a stack setting, so you can turn it off if you’d rather investigate a stuck instance yourself first.

If AWS reclaims the instance

Because this device runs on Spot pricing by default, AWS can take the instance back at any time. CodeHerder handles it on its own — there’s nothing for you to do.

AWS gives one of two warnings, and CodeHerder reacts to each differently:

A termination notice means AWS is reclaiming the instance within about two minutes. CodeHerder stops assigning new work to the device right away, gives any agent that’s mid-task a short window to wrap up, then stops it cleanly.
A capacity-rebalance recommendation is an earlier, advisory warning — the instance might not actually be reclaimed for hours, or ever. CodeHerder stops assigning new work to the device right away. When a running agent finishes, CodeHerder stops the device — it goes Offline and stays out of placement until AWS replaces the instance. If the agent is still going after a while instead, CodeHerder gives up waiting and lets the device take on new work again, rather than holding it idle for a reclaim that may never come.

Either way a device stops, the session running on it ends with a Released outcome, not Lost — see Sandbox state vs. a run’s outcome — and the task it was working on gets staffed again automatically. The replacement instance comes back as the same device, and the task’s branch and everything already committed to it are untouched — the worktree is still there on disk, waiting for the next session.

A Device entry appears in the workspace’s activity feed either way. If a session was actually stopped, you’ll also see it end Released on the task’s Workflow view — a rebalance recommendation that never leads to a stop won’t show one. The device itself shows Offline while its instance is stopped and a replacement takes over — see Online and Offline.

The device stays enabled the whole time — nothing pauses it, and there’s nothing for you to resume. But while the drain is running, a Placement report for a task lists the device as ineligible with the reason device_disabled — the same reason an operator pause produces. Nothing paused the device and there’s nothing to undrain; the reason clears on its own once the device is replaced or goes back into service.

Use it

Once the stack reaches CREATE_COMPLETE and the instance finishes booting, it connects back to CodeHerder and shows up in Set up → Devices for the workspace you launched it from, already linked to that workspace — no attach step, and no separate step to put an agent on it. Any workspace agent whose capabilities it covers is eligible immediately — 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.

Sharing it with another workspace. A device belongs to you, not to any one workspace, so adding it to a second one is optional, not something you have to do. Click Attach existing on the other workspace’s Devices page, or run ch device workspaces create <deviceId> --workspace <workspaceId> from the CLI — see Sharing a device across workspaces.

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.
Launch didn’t start, or the button errored — starting a launch needs workspace owner or admin; see Before you start above.
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.
Stack is running but nothing registered — check the instance’s boot log in the EC2 console; an expired token is the usual cause. Delete the stack and relaunch with a fresh one.
Connected but not staffable — check the device’s health snapshot; see Device health and readiness checks.
A session on this device ended Released with no obvious cause — AWS may have reclaimed the Spot instance; see If AWS reclaims the instance above.
Need to look inside — open a shell on the instance from the EC2 console using Session Manager, no SSH key required.

MicroVM runners — the automatic version of this: CodeHerder launches AWS devices for you, on its own, instead of you clicking the button
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
Following a live agent session — what a Released session means and where else it shows up
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)