CodeHerderSearch⌘KRequest access →

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.

  1. 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
  2. Host harness transcripts. Delete files older than the period you keep for resume and audit:
    find ~/.claude/projects -name '*.jsonl' -mtime +14 -delete
  3. Docker stage-run files. Delete directories for runs that ended: find ~/.codeherder/stage-runs -mindepth 1 -maxdepth 1 -mtime +1 -exec rm -rf {} +.
  4. 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.
  5. 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.

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