Self-hosted device disk growth
Measure device disk use, see which directories grow and which setting bounds each, set a disk alert, and clean the stores that have no bound.
This page tells you how to watch and bound the disk of a device that runs agent sessions. It covers host devices and Docker-backed devices (container). Read it with Sizing a self-hosted deployment.
Set a disk alert
Alert on the percent of disk in use. Do not rely on the Disk headroom readiness check. That check warns only when less than 512 MiB is free, and it blocks work at 128 MiB. That is too late to act.
| Level | Disk in use | Action |
|---|---|---|
| Warn | 70 percent | Find the largest store with the commands below. Clean it the same week. |
| Act | 85 percent | Clean now. Lower Session limit if a clean-up does not free enough. |
Each device reports diskPct for the volume that holds its session root. Read it in either place:
ch device metrics <device> # min, average, max and current DISK % over the last 30 minutes
ch device show <device> --json # the current diskPct field
CodeHerder does not alert on diskPct. Poll one of these commands from your own monitoring and raise the two levels above.
Why 70 and 85. The stores that CodeHerder bounds settle at a known size. Sessions in use add one checkout of the repo each, up to 8 by default. The device disk budget keeps the Docker and data-dir filesystems above a free-space floor, at least 10 GiB (CH_DEVICE_DISK_FLOOR_MB). The stores that CodeHerder does not bound grew by about 210 MB a day on a busy host that we sampled. On the 50 GB default disk, 70 percent leaves 15 GB before the Act level, which is about 70 days of that growth. The Act level leaves 7.5 GB, about 35 days. Replace the levels with your own once you have a month of diskPct history.
Measure what is using the disk
Run these on the device. <root> is the session root, ~/codeherder-sessions unless you set --session-root.
du -sh <root>/.mirrors <root>/.pool <root>/.transcripts <root>/.reclaimed
du -sh <root>/*/ | sort -h | tail # live and stranded sandboxes
du -sh ~/.cache ~/go ~/.npm # build cache
du -sh ~/.claude/projects # host harness transcripts
du -sh ~/.codeherder/stage-runs # Docker-backed devices only
docker system df # Docker-backed devices only: images, containers, volumes
Which directories grow
| Store | Where | Bound | Setting |
|---|---|---|---|
| Live sandboxes | <root>/<sandboxId>/ |
One checkout of the repo each; the device removes a sandbox when its session ends | --max-session-worktrees or CH_MAX_SESSION_WORKTREES (8); --session-disk-budget-mb (off) |
| Git mirrors | <root>/.mirrors/ |
One bare clone for each repo, plus per-task branches. The device removes a delivered branch 14 days after its last commit and then runs git gc once a day. It never removes a branch that is not on your git host. |
CH_MIRROR_BRANCH_RETENTION_DAYS (14; 0 turns the clean-up off) |
| Retired warm pool | <root>/.pool/ |
Empty. An earlier build kept spare checkouts here. The device removes any it finds when it connects. | None |
| Transcript archives | <root>/.transcripts/ |
The device removes an archive 7 days after the sandbox ends. One task keeps at most 256 MiB. | CH_TRANSCRIPT_ARCHIVE_RETENTION_DAYS (7; 0 keeps archives) |
| Parked bundles | <root>/.reclaimed/ |
Work that could not be pushed is saved as a bundle for 30 days. | No setting. Clean by hand, see below. |
| Build cache, toolchains and system images | ~/.cache, ~/go, ~/.npm, the toolchain cache, ch-env images |
The device removes the least needed first when free space falls below the floor, and removes an unused environment after 7 days | CH_DEVICE_DISK_FLOOR_MB (0 = max(10 GiB, 10%)) |
| Device logs | the device log directory | Each file is cut to the budget, with one old copy | CH_LOCAL_LOG_BUDGET_MB (8) |
| Docker containers, dangling images, volumes | the Docker daemon | The device removes an exited container after 4 hours | CH_DOCKER_REAP_MAX_AGE_HOURS (4) |
| Docker stage images | the Docker daemon | None | Clean by hand, see below. |
| Docker stage-run files | ~/.codeherder/stage-runs/<runId>/ |
None for the transcript directory | Clean by hand, see below. |
| Host harness transcripts | ~/.claude/projects/ |
None | Clean by hand, see below. |
The measured sizes and the growth for each store are in the engineering record docs/device-disk-growth.md of the CodeHerder source. In short, a session costs one checkout while it runs and about 0.5 MB of mirror after it ends. A parked bundle is the size of the repo and stays for 30 days.
Clean the stores that have no bound
Lower the work on the device before you delete anything. Run ch device edit <deviceId> --max-sessions 1, and wait for running sessions to end.
- Parked bundles. A bundle is the only copy of work that could not be pushed. List them, and open any you may need with
git clone <bundle>. Delete a bundle you no longer need. To clear old bundles, delete the ones older than 7 days:find <root>/.reclaimed -type f -mtime +7 -print # check the list first find <root>/.reclaimed -type f -mtime +7 -delete - Host harness transcripts. Delete files older than the period you keep for resume and audit:
find ~/.claude/projects -name '*.jsonl' -mtime +14 -delete - Docker stage-run files. Delete directories for runs that ended:
find ~/.codeherder/stage-runs -mindepth 1 -maxdepth 1 -mtime +1 -exec rm -rf {} +. - Docker stage images. Remove images no stage uses:
docker image prune -a --filter "until=720h". The device pulls an image again when it needs it. - Stranded sandboxes. A directory under
<root>/for a session that no longer runs is removed by the device on its next clean-up cycle. If one stays, follow “Reclaiming stuck worktree slots” in Managing your devices.
Run ch device metrics <device> again. Restore Session limit with ch device edit.
Related guides
- Sizing a self-hosted deployment — starting sizes and expansion triggers for every part
- Running the device server as a service — session root, worktree cap and disk budget flags
- Managing your devices — readiness checks and capacity limits
- Self-hosted launch workload — the load these numbers assume
Last updated