# Launch a device on AWS

Source: https://codeherder.com/docs/launch-a-device-on-aws/

Launch a CodeHerder device on AWS in one click from the Devices page.

If you don’t have a machine you want to leave running as a [device](https://codeherder.com/docs/adding-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](https://codeherder.com/docs/self-hosting/#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

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; the default instance size is a good balance for most repositories, but a memory-heavier size is worth picking for a large one.
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 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](https://codeherder.com/docs/following-a-live-session/#sandbox-state-vs-a-runs-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](https://codeherder.com/docs/devices/#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](https://codeherder.com/docs/placement/) 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](https://codeherder.com/docs/agents-and-cli/) and [Managing your devices](https://codeherder.com/docs/devices/). An AWS-launched instance registers under whatever hostname AWS assigned it, which usually isn’t memorable — [give it a proper name](https://codeherder.com/docs/devices/#naming-a-device) 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](https://codeherder.com/docs/devices/#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](https://codeherder.com/docs/devices/#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](https://codeherder.com/docs/launch-a-device-on-aws/#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](https://codeherder.com/docs/devices/#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](https://codeherder.com/docs/launch-a-device-on-aws/#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.

## Related guides

- [MicroVM runners](https://codeherder.com/docs/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?](https://codeherder.com/docs/adding-a-device/) — the other way to add a device: run the device server yourself
- [Managing your devices](https://codeherder.com/docs/devices/) — day-to-day device health, concurrency, and linking devices to workspaces
- [Following a live agent session](https://codeherder.com/docs/following-a-live-session/) — what a **Released** session means and where else it shows up
- [Connecting repositories](https://codeherder.com/docs/repositories/) — what a device needs to work on a given repository
- [Understanding costs](https://codeherder.com/docs/costs/) — how CodeHerder tracks model spend (AWS bills the instance separately, outside CodeHerder)