Devices that clean up after themselves

An ephemeral device is a ch device-server you never have to tear down by hand. It registers itself when it boots, picks up work like any other device, and once it has sat idle long enough, drains itself, cleans up, and archives itself before exiting. It’s built for a machine you spin up to do a batch of work and then throw away — a cloud instance, a CI job, a spot VM — where nobody is watching to shut it down when the work is finished.

How it differs from a MicroVM runner

MicroVM runners are the managed path: CodeHerder decides when your queue needs more capacity, launches a machine in your AWS account, and disposes of it again on your behalf. You don’t run any of that yourself.

Ephemeral mode is the other half of that idea. You bring the machine — however you like to launch one — and CodeHerder only handles what happens on it: registering, working, and cleaning up after itself once there’s nothing left to do. Use it when you already have your own way to spin up disposable compute and just want the device server to behave well once it’s there.

Turn it on

Start the device server with:

ch device-server --ephemeral

or set CH_DS_EPHEMERAL=1 in the environment instead. Either way, the device registers and starts working exactly as it would without the flag — the only difference is what happens once it runs out of work.

What counts as idle

A device is idle when it has no live agent session running and no session worktree left on disk. A task that’s between stages still holds its worktree even with no agent actively running, so the device counts as busy until that worktree is cleared, not just while an agent is typing.

The device has to stay idle continuously for the whole window below. If a new session lands partway through, the clock resets — it doesn’t pick up where it left off once that session ends.

The two timers

Flag	Environment variable	Default	What it controls
--ephemeral-idle	CH_DS_EPHEMERAL_IDLE	15m	How long the device must stay continuously idle before it starts shutting itself down.
--ephemeral-min-alive	CH_DS_EPHEMERAL_MIN_ALIVE	5m	The minimum time the device stays up at all, even if it’s idle the whole time.

The minimum-alive timer exists so a device that boots before any work has reached it doesn’t shut itself down before it’s had a real chance to pick something up.

What shutdown does

Once the idle window passes, the device runs through the same sequence every time, in this order:

1. Stops accepting new work, so nothing new lands on it while it winds down.
2. Waits briefly for anything already in flight to finish.
3. Stops its agents.
4. Tries to push any uncommitted work left in a worktree, to the task’s own branch.
5. Archives itself.
6. Exits.

That push is a best effort, not a guarantee: work that can be pushed goes to the task’s branch before the machine disappears, but anything the device can’t push is gone with the disk. On a machine you plan to discard, commit and push what you care about yourself rather than relying on the cleanup step to rescue it.

Archiving is the same thing that happens when you archive any other device by hand. The device drops out of your device list and its tokens are revoked, but the record and its history stay put — so a finished ephemeral device is still there to look back at. See Finding an archived device for how to list archived devices.

Ephemeral mode always stops agents at shutdown, and it always turns off automatic CLI updates — a device you’re about to throw away doesn’t need to stay current.

The credential caveat

If you register with an API key that only has permission to create the device itself, that registration can create the device but can’t also link it to a workspace in the same step. Use your regular, full-access CH_TOKEN (see Credentials and profiles) if you need the device linked to a workspace as soon as it registers.

When not to use it

If you want to keep a machine around and reuse it, run it as an ordinary device instead — see Running the device server as a service. Ephemeral mode is for machines you’re going to discard anyway; running it on a laptop or another machine you plan to keep just means it will eventually archive itself out from under you.

Related guides

• MicroVM runners — the managed, CodeHerder-launches-it-for-you sibling of this page
• Running the device server as a service — keep a device running long-term instead of letting it clean itself up
• Managing your devices — day-to-day device health, concurrency, and linking devices to workspaces
• Launch a device on AWS — launch a single AWS device by hand
• Credentials and profiles — the difference between a full-access CH_TOKEN and a narrower one
• Updating the CLI — how automatic updates work on a device that keeps them on