CodeHerderSearch⌘KRequest access →

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, CodeHerder can launch compute for you in your own AWS account. From Set up → Devices, click Launch on AWS. CodeHerder mints a registration token and opens AWS CloudFormation’s quick-create page. The CodeHerder template is already loaded, and the token is pre-filled. Pick a compute type, fill in your credentials and click Create stack. Creating the stack is the whole setup. You run no AWS CLI step and no ch command.

The compute runs in your own AWS account, so you pay AWS for it. CodeHerder does not bill you for it.

Choose a compute type

The form offers three compute types. Pick one in the Compute type group.

Property EC2 Spot (ec2-spot) EC2 On-Demand (ec2-on-demand) Lambda MicroVM (lambda-microvm)
What you get One always-on EC2 device One always-on EC2 device One pool device. CodeHerder starts a microVM for each session.
Docker Yes. Each stage runs in a hardened container. Yes. Same as Spot. Yes. Each stage runs in a hardened container inside the microVM.
Cost AWS bills the instance and its disks all the time, at Spot prices. The same, at the normal hourly price. AWS bills only while a microVM runs. An idle pool costs almost nothing.
Start time One boot when the stack is created. The device is then always ready. The same as Spot. About 30 to 50 seconds from launch to a connected device, for every session.
Persistence A data disk keeps the device identity and its worktrees. They survive a replacement. The same as Spot. Nothing. Each session gets a fresh microVM. Only what the session pushes is kept.
Interruption AWS can reclaim the instance. See If AWS reclaims the instance. AWS never reclaims it. A microVM ends after its maximum lifetime, 4 hours by default.
Concurrency The device’s max_concurrent_sessions The device’s max_concurrent_sessions MicroVM max sessions in the form. It is the number of microVMs that run at once.
Regions Any region with EC2 Any region with EC2 us-east-1, us-east-2, us-west-2, eu-west-1 and ap-northeast-1
Good for A steady queue at the lowest always-on price Work that must not be interrupted Bursty work, or a queue that is often empty

Each microVM runs one session at a time and serves the next session when one ends. The Devices page can still show a No Docker badge on a pool. The badge is out of date. Docker works in the microVM.

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. Only owners and admins see the Launch on AWS button. If you’re a member, the Devices page is read-only for you. Ask an owner or admin to launch the device.
  • An AWS account you can create a CloudFormation stack in, plus, for an EC2 type only, a public subnet to launch into. Its VPC is detected automatically. A Lambda MicroVM stack needs no subnet.
  • 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. For GitHub, use a classic token with the repo scope, or a fine-grained token with Contents: write. For GitLab, use a token with the write_repository scope. Leave a field blank to skip that host. One device serves both hosts if you fill in both. A token in the form is not the only way a device gets git access. See Git credentials on a device.
  • Optional: a GitHub App. To have pull requests go out as your App’s bot, fill in both GitHub App ID and GitHub App private key. Paste the key as base64 on one line. Set both fields or neither. See Connecting the GitHub App.

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. The CodeHerder connection group is already filled in.
  3. In the Compute type group, pick a type. The default is ec2-spot. Choose ec2-on-demand for an On-Demand instance, or lambda-microvm for a microVM pool.
  4. Fill in the Agent credentials group (your Claude token, and a GitHub/GitLab token if you need one).
  5. For an EC2 type, open the EC2 only group and pick a Public subnet. The other fields have sensible defaults. The default instance size suits most repositories, but pick a memory-heavier size for a large one. Ignore this group for lambda-microvm.
  6. For lambda-microvm, open the Lambda MicroVM only group. Set MicroVM max sessions (default 4) to the number of microVMs that may run at once. Set MicroVM size to small, medium or large. Medium has 4 GiB of memory. Ignore the EC2 only group.
  7. Leave the Advanced (pre-filled, do not change) group as it is. It holds the trust settings CodeHerder filled in. Its one setting you may change is the stuck-device report, which applies to EC2.
  8. Click Create stack.

A MicroVM stack must be in one of the five regions in the table. The form refuses any other region at its Rules check, with a plain message. A MicroVM stack name can be at most 38 characters.

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

On EC2 (Spot or On-Demand)

  • Spot pricing by default, in a single instance. If AWS reclaims it, the stack launches a replacement and falls back across instance families at the size you picked to find capacity. To pay more and never be reclaimed, set Compute type to ec2-on-demand.
  • 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 kept in AWS Secrets Manager. The instance copies them into a file that only the root user can read.
  • A warning if the device stops serving. By default, the stack logs a warning in your AWS account (in CloudWatch Logs) when the device stops serving while its instance keeps running. It takes no action. CodeHerder never stops, replaces or reboots the instance, so you decide what to do. To turn the warning off, set Stuck-device report to off. It is in the Advanced group of the stack form.

On Lambda MicroVM

  • One pool device, named for example “Lambda MicroVM (us-west-2)”, in Set up → Devices. It is one row, not one row per microVM. It is linked to the workspace you launched from.
  • A status on the pool. The pool shows Building image while CodeHerder builds the runner image in your account. It then shows Ready. The stack waits up to 13 minutes for the build.
  • microVMs inside the pool. CodeHerder starts a microVM when work is waiting with nowhere to run. The live and recent microVMs show on the pool’s detail page. See MicroVM runners.
  • Roles that you can read. The stack creates one role that CodeHerder assumes, with an ExternalId. It also creates a build role and an execution role. No access key is stored anywhere.
  • Credentials kept in AWS Secrets Manager. The microVMs read them at start.

If AWS reclaims the instance

With Spot pricing, AWS can take the instance back at any time. CodeHerder handles it on its own, so you have nothing to do. If you set Compute type to ec2-on-demand, AWS never reclaims the instance and this section doesn’t apply.

When AWS sends a termination notice, it reclaims the instance within about two minutes. CodeHerder stops assigning new work to the device right away. It gives any agent that’s mid-task a short window to finish. The device then saves the running agents’ work and stops them.

The save works like this:

  1. For each repo in a running sandbox, the device commits uncommitted and untracked changes as a work-in-progress commit.
  2. It pushes that commit to the task’s branch.
  3. If the branch moved on the remote, the device merges the remote’s latest commits into the saved work and pushes the result. It never force-pushes.
  4. If that merge conflicts, or the push fails, the work stays in the folder on the device’s data disk.

The save has limits. The agent isn’t paused, so a file it writes after the save stays uncommitted. A repo that is still saving when the time runs out may not be pushed. The device skips a repository registered as read-only. See Git credentials on a device.

AWS can also send an earlier, advisory capacity-rebalance recommendation. Most never lead to a reclaim, so CodeHerder ignores it. The device keeps taking new work until a real termination notice arrives.

After a termination notice, the session running on the device ends with a Released outcome, not Lost. See Sandbox state vs. a run’s outcome. CodeHerder staffs the task again automatically. The replacement instance comes back as the same device. The task’s branch and everything already committed to it are untouched. The saved work-in-progress commit is on that branch, so the next session starts with it, even on another device. If the replacement takes over as this device, its data disk reattaches and the folder is still there too.

A Device entry appears in the workspace’s activity feed. Each repo the device tried to save gets a Sandbox parked work before a Spot reclaim entry. That includes a repo whose save didn’t reach the remote. If a save didn’t reach the remote, the work is still in the folder on the device. You also see the session end Released on the task’s Workflow view. The device 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 you have nothing to resume. While the drain runs, a Placement report for a task lists the device as ineligible with the reason device_disabled. That is the same reason an operator pause produces. The reason clears on its own once the device is replaced.

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 device 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 that holds the device’s credentials. A new instance starts with the values in that secret. Updating the secret doesn’t change the running device, and a reboot doesn’t either. The new values apply only to the next instance AWS launches. Don’t terminate the instance to force this. To change the credentials on the running device right away, contact CodeHerder support.

A stack update works the same way. A new instance size or other launch setting applies to the next instance the stack launches, not to the one that’s running.

Remove it

Deleting the CloudFormation stack is the way to remove a device. What remains depends on the compute type.

EC2 Spot and EC2 On-Demand

  1. Delete the stack. This stops the instance and removes the AWS resources the stack created.
  2. Delete the data volume in the EC2 console. The stack keeps it on purpose, so you can recover it if you deleted the stack by mistake. It costs money until you delete it.
  3. Retire the device in CodeHerder. The device row stays after the stack is gone. See Retiring a device.

Lambda MicroVM

  1. Delete the stack. CodeHerder terminates any live microVMs, deletes the pool’s images and its files in the artifact bucket, and archives the pool. The pool leaves the Devices list.
  2. The stack then removes the access role, the build role, the execution role, the artifact bucket, the secrets and the two helper functions.
  3. If CodeHerder cannot assume the access role, the stack’s own cleanup function does the AWS side. It stops the pool’s microVMs, deletes its images and empties the bucket. A stack delete never fails because CodeHerder is down.

What can remain after a stack delete:

  • Log groups that AWS creates for the images, named /aws/lambda-microvms/<image name>. They are not stack resources. If one is there, delete it in CloudWatch.
  • Nothing in the Devices list. You need not retire the pool by hand.

To stop launches without deleting the stack, archive the pool device in CodeHerder. CodeHerder then terminates the live microVMs and stops starting new ones. The roles and the bucket stay in your account until you delete the stack. See MicroVM runners.

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.
  • No Launch on AWS button — only workspace owners and admins see it; see Before you start above.
  • A “Couldn’t start the AWS launch” message — CodeHerder couldn’t create the registration token. Choose Try again in the message.
  • 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.
  • A MicroVM stack fails at the Rules check — the region has no Lambda MicroVM. Pick one of the five regions in Choose a compute type.
  • A MicroVM stack name is refused — the name is longer than 38 characters. Use a shorter one.
  • The pool stays on Building image — the stack waits up to 13 minutes for the build. Check the stack’s Events tab and the CloudWatch logs for the build. If the build failed, the pool shows Failed with a reason, and CodeHerder retries on its own.
  • The pool shows Access lost — CodeHerder cannot assume the access role. The role or the stack may be gone, or its trust was edited. Restore the role, or delete the stack and launch again.
  • 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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close