Skip to main content

Docker Reclaim

@sntxrr/docker-reclaimv2026.09.06.2· 4d agoMODELS
01README

Measure what a Docker host's disk is actually spent on, plan what can be freed without destroying a rollback target, and free it. The command people reach for is the wrong one: docker image prune — dangling or -a — never touches the BUILD CACHE, and on a host that builds its own images the build cache is usually most of the footprint. On the host this was written against it was 59.5GB of a 77GB reclaim, which no amount of image pruning would have recovered. Three behaviours are deliberate because each one corresponds to a way the obvious command does damage or lies. docker image prune -a removes every image no container references, which is precisely the set of previous versions a rollback needs; this model instead protects the newest keepVersions tags of each repository and removes specific image IDs, so reclaiming space does not quietly cost you the ability to go back. docker builder prune -af deletes the cache that makes the next build fast, and cache that is minutes old is the most valuable cache there is; pruning is therefore age-filtered via --filter until=, so a scheduled run takes cold layers and leaves the working set. And Docker reports sizes as rounded human strings where 1000 versus 1024 is a real 7% at terabyte scale, so parsing is explicit and unit-aware and the freed figure is measured by observing free space before and after rather than by summing estimates. Each method writes its own data instance — usage, plan, reclaim — so an expression always gets the schema it expects rather than whichever method ran last. observe and plan are read-only and safe to schedule at any frequency; reclaim is dry-run unless passed apply: true, and even then never removes an image that any container references, running or stopped. Host key checking is left ON by default — StrictHostKeyChecking=no is available but is not the default, because a model whose entire purpose is running destructive commands as a privileged user is the last place to accept an unverified host key.

02Models1
@sntxrr/docker-reclaim/hostv2026.09.06.2docker_host.ts

Global Arguments

ArgumentTypeDescription
sshHoststringHostname or IP of the Docker host. No default: this model runs destructive commands, and a default host is a way to run them somewhere unintended.
sshUserstringSSH user.
keepVersionsnumberNewest tagged images to keep per repository. These are the rollback targets — `docker image prune -a` removes them and this does not. 0 keeps none.
buildCacheKeepHoursnumberKeep build cache newer than this many hours. Recent cache is what makes the next build fast; 168 (7 days) reclaims cold layers only. 0 prunes all of it.
dataRootstringPath used to measure free space. Should be on the filesystem holding Docker's data root.
strictHostKeyCheckingenumSSH host key policy. 'accept-new' pins a host on first contact; 'yes' requires it to be known already. 'no' accepts any key every time and is never appropriate for a privileged, destructive session — it exists only for environments with no persistent known_hosts.
knownHostsFile?stringExplicit known_hosts path, for runtimes where the default HOME is not the operator's.
fn observe()
Read-only. Report what Docker holds and how much of it is reclaimable, plus free space on the data root. Safe to schedule as often as you like; this is the number to assert a threshold against.
fn plan()
Read-only. Report exactly which images would be removed and which are protected, and how much build cache is old enough to prune. Removes nothing.
fn reclaim(apply: boolean)
Free space. Dry-run by default: without `apply: true` it reports the plan and removes nothing. With it, removes the planned image IDs and prunes build cache older than `buildCacheKeepHours`. Never removes an image a container references, and never the newest `keepVersions` tags of a repository.
ArgumentTypeDescription
applybooleanActually remove things. Defaults to false so an accidental run is a report.

Resources

usage(infinite)— What Docker currently holds, by class, with the reclaimable portion of each and the free space on the filesystem behind it.
plan(infinite)— What `reclaim` would remove and what it would refuse to, with the reason for each.
reclaim(infinite)— The outcome of a reclaim, with space freed measured by observing before and after rather than by summing estimates.
03Previous Versions1
2026.09.06.1
04Stats
A
100 / 100
Downloads
2
Archive size
19.1 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License declared1/1earned
  • Verified public repository2/2earned
05Platforms
06Labels