Devices
Where CodeHerder agents run
A device is a machine that runs ch device-server. It does the agent's work in an isolated copy of your repository. The copy lives on your machine or in your AWS account. CodeHerder's servers keep no clone.
The ways in
4 ways to connect a device
One click on AWS and a MicroVM runner need no CLI and no machine of your own. The other ways need a machine you run.
One click on AWS
You have no spare machine, and no one to ask for one.
What you need
- An AWS account
- Workspace owner or admin
- A Claude subscription token from claude setup-token
- A GitHub or GitLab token, if agents must open pull or merge requests
From Set up → Devices, click Launch on AWS. CodeHerder opens AWS CloudFormation with its template loaded and a registration token pre-filled. Pick a public subnet. Click Create stack. The instance connects on its own, with no CLI install and no manual registration step.
Read the full steps →A MicroVM runner
You want devices that start when work is waiting and stop when it ends.
What you need
- An AWS account
- An AWS access key, set by an owner or admin
- An AWS execution role and a region
- A runner image in your AWS account. Contact CodeHerder if you have none
An owner or admin turns on the runner in Settings → General. CodeHerder then launches a short-lived device in your own AWS account when work is waiting. The device removes itself when the work ends. The default limit is 4 VMs at once.
Read the full steps →A machine you already have
You have a laptop or server you can leave running.
What you need
- The ch CLI, installed on that machine
- A sign-in from ch login, or an API key
- A coding agent CLI, signed in to its AI provider
- Docker, or root access to add an agent user
Sign in. Without agent isolation, the device refuses repository work. Run ch device setup-agent-user | sudo sh and set CH_AGENT_USER=ch-agent. Then run ch device-server and accept the registration prompt. On a machine with Docker, run ch device-server --docker-executor instead. The device goes Offline when that terminal closes. Run it as a service to keep it Online.
Read the full steps →A personal device
You want to run your own work, not take tasks from the rest of the workspace.
What you need
- macOS or Linux
- The ch CLI, on the machine you're sitting at
- A git checkout, on that same machine
Run ch start from the top of a git checkout. It registers this machine for you. A session starts in the same terminal. Nobody else's tasks land on it until you share it. Set up agent isolation before you share it.
Read the full steps →
No device needs a separate sign-up step. Running the server or launching the stack registers it. A device you run yourself needs agent isolation before it takes repository work.
The hand-off
Not technical yourself? Send this.
Copy this note. Send it to a developer or your IT team. It lists both paths. They can choose one.
Copy this and send it
Can you connect a device for CodeHerder? Option 1: Click "Launch on AWS" on the Devices page. It opens AWS CloudFormation with a template already loaded. You need no CLI and no manual registration step. Option 2: Install the ch CLI on a machine that can stay on. Then set up agent isolation. Without isolation, the device refuses work on a repository. Use one of these two paths: - Run "ch device setup-agent-user | sudo sh". Set CH_AGENT_USER=ch-agent. Then run "ch device-server". - Or run "ch device-server --docker-executor" on a machine with Docker. Steps: /docs/launch-a-device-on-aws/, /docs/adding-a-device/ and /docs/agent-isolation/
Keeping a device online
A closed terminal takes a device Offline
Close the terminal running ch device-server, and the device goes Offline. You have two ways to avoid that.
Run it as a service
A background service keeps the device Online across logout and reboot. See running the device server as a service for the exact steps.
Use the AWS option instead
AWS replaces a reclaimed instance on its own. The replacement comes back as the same device. No terminal stays open.
FAQ
Questions people ask before connecting a device
What is a device?
A device is any machine running ch device-server. That is what runs your agents' work, each in its own copy of your repository.
Do I need a spare machine?
No. Launch a device on AWS instead. The instance runs in your own AWS account, and it registers itself.
What does the AWS option cost?
You pay AWS for the instance and its storage; CodeHerder charges nothing for it. Spot pricing is the default.
Who can launch a device on AWS?
A workspace owner or admin. Everyone can see the Launch on AWS button, but only those two roles can start the launch.
What happens if my laptop sleeps?
A device shows Online only while ch device-server keeps running and connected. A sleeping laptop stops that, so the device goes Offline. Run it as a service, or use the AWS option, to avoid that.
Does my code ever leave my machine?
Your repository checkout stays on your machine. Agents work on your own machine or in your own AWS account, against your own repository. CodeHerder stores commit metadata and cost events. Agent output and attachments you upload can contain code, and CodeHerder stores those. See /security for what stays where.
Connect your first device.
Choose a way to connect. File your first task when the device shows Online.