Amp decides when an orb spawns, pauses or is deleted, and cf-orbs carries out each decision. Terms such as bootstrap, watchdog and control plane are defined in How it works.
Spawn
A spawn starts the orb and connects it to Amp. How long it takes depends on where the disk comes from:
| Source | Measured time |
|---|---|
| Container already running | None (reuse) |
| The orb’s own snapshot | 2.3 s for the spawn (container ready in 0.6 s) |
| Project snapshot | About 12 s of orb setup before the first turn |
| The image, on a host that has it | About 6 s |
| The image, on a new host | 40 to 50 s (pulls the 1.8 GB image) |
These numbers are from the project’s own tests. Cloudflare picks the host, so your numbers can differ.
Pause
Amp pauses an orb once the agent is idle and nobody has used the thread for about 20 minutes (we saw 20 to 25 minutes). An archived thread pauses too, and a deleted thread deletes its orb.
On pause, cf-orbs:
- Stops the Amp processes.
- Masks token shapes in the log files on the disk.
- Saves the disk as a snapshot.
- Stops the container.
A paused orb has no compute charge.
| Kept | Lost |
|---|---|
| Files, the repo, installed packages, build caches (everything on the disk) | Running processes: dev servers, watchers, terminal sessions |
| Memory |
Amp runs .agents/resume on wake, and portal services restart when you open them.
Warm pause
With warmMinutes above 0 (the default is 10), cf-orbs saves the disk at the pause but keeps the container and the Amp processes running for that many minutes. A message in that time needs no restore and no restart.
A warm orb:
- Bills like an awake orb.
- Holds one
maxRunningslot. - Counts toward
maxAwakeHours.
cf-orbs status shows warm (Nm left) for a warm orb. Set warmMinutes to 0 to stop the container at once.
A pause that carries a project snapshot id is always cold (snapshot and stop), with no warm pause, because a project snapshot must be a quiesced disk.
Wake
On the next message, Amp sends a spawn and cf-orbs restores the disk snapshot. The restore is lazy, so the first read of a large build cache is slower than later reads (about 230 MB/s).
A paused orb can also wake when somebody views its thread, with no new message. It pauses again later.
Snapshots
A snapshot is a saved copy of an orb’s disk. There are two kinds:
- Orb snapshot. The saved disk of one paused orb.
- Project snapshot. A disk that Amp has already set up for a repo, so a new thread on a known repo can start from it. Amp holds the snapshot id, and cf-orbs keeps a mapping from that id to a Cloudflare snapshot.
Rules:
- A snapshot is kept for 30 days after its last restore. After that, the orb starts fresh and Amp sets up the repo again.
- Each pause makes a new snapshot, and storage is billed.
- A paused orb still restores after an image change, and its disk keeps the old content. See Orb image.
- Amp caches one project snapshot for each provider for 72 hours. cf-orbs can’t see or delete that cache.
To list, forget and prune snapshots, see Manage snapshots.
Project snapshot refresh
A project snapshot goes stale after an Amp CLI release, and each new thread then spends 4 to 5 s on the amp update. It also goes stale after a deploy with a new image.
Set projectSnapshotRefresh to "on-change" and cf-orbs checks for this when a new thread starts from a project snapshot. If the snapshot is stale, cf-orbs forgets the mapping, at most once for each project in 24 hours. The next new thread then boots the image and Amp runs setup.
The default is "off". cf-orbs never starts threads or orbs for this check. Also, Amp doesn’t always save a new snapshot after cf-orbs forgets the mapping. Until it does, each new thread runs setup, and cf-orbs status shows the stale flag.
Checkpoints
Work done after the last pause can be lost if Cloudflare stops a container without warning. To limit the loss, set checkpointMinutes to 15 or more. cf-orbs then snapshots each awake orb that has changes at that interval.
Delete
On delete, cf-orbs removes the orb. Its snapshot data stays until the 30-day limit, unless you run cf-orbs snapshots prune --yes.
Lost orbs
If Cloudflare loses an orb in the middle of a turn, Amp spawns it again and the agent runs the failed tool call again. The disk is kept, but running processes and shell state are lost. This was tested by pausing an orb, and the lost orb came back in about 22 s.