Choose the server before its storage policy
Open Host → Storage & cleanup and select the connected server. Build retention appears when its operator has installed a fixed, reviewed artifact profile and explicitly enabled this capability. A missing profile is unavailable, rather than permission to clean arbitrary folders.
Public Go Node and privately licensed installations use the same capability checks. Cloud workspace operations require the applicable subscription or trial. A privately delivered Enterprise control plane uses its installation license and does not need a separate Cloud subscription. The server owner remains responsible for storage provisioning and recovery verification.
Set defaults and service exceptions
The automatic switch controls scheduled and pre-build cleanup. The pre-build switch separately allows cleanup when an admitted source build lacks reserve or source slots. Pausing automatic cleanup still permits an owner to review and run a manual cleanup.
Choose an interval from one to 168 hours, an artifact minimum age from six to 720 hours and two to ten successful rollback versions. Set the minimum available space, additional build headroom, cache budget and upload expiry. Zero cache budget means no old eligible cache is retained; age and every protection rule still take priority.
Each approved service can inherit the server defaults, use its own rollback, age and cache rules, or be excluded. Shared runtime cache often cannot be attributed to one service. Its common rules therefore use conservative limits, and excluding a service protects unattributable shared cache. A smaller per-service budget does not authorize deleting another service’s layers.
Read the actual source-build reserve
Capacity separates currently available disk, the reserve required by the installed source profile, additional headroom and unfinished upload reservations. It also shows the required total, any shortfall, and the coverage of reclaim estimates.
For approved source builds, the mandatory reserve is six times the configured maximum expanded source size plus one GiB. The admission floor is the larger of that reserve plus headroom and the configured minimum free space, with pending upload bytes reserved in addition. Idle uploads keep a fixed safety floor so the requested build can reach its pre-build cleanup check. While a source build is active, new upload admission also preserves that build’s configured budget. Pending upload reservations count in both checks. Build and upload limits remain bounded.
A before-build cleanup uses the already admitted build’s writer slot. A separate publication, deployment or cleanup cannot own it concurrently. Cleanup on another filesystem does not satisfy the selected build filesystem’s shortfall. If protected artifacts or the age rule prevent sufficient reclamation, the build reports a concrete shortfall and stays unstarted.
Keep usable recovery sets together
Current source, running deployments, the latest published version, pinned builds, active or uncertain operations, installed baselines and retained successful rollback versions stay protected. Relevant source, uploads, images, layer dependencies and operation metadata are considered together.
Pin a known version to retain it explicitly. Unpinning changes only that extra protection; current-version and rollback rules still apply. When prior deployment evidence is incomplete, Hostwatch keeps additional successful source versions and reports a warning. Unknown directories and image ownership are not proof that an artifact is disposable.
Application data, databases, runtime volumes and backups are outside this build cleanup. Containers are never retired by the build-artifact helper. Named, published or referenced images stay protected unless the installed profile can establish safe disposal. A storage budget is a target, not permission to destroy protected content.
Include manually published services with explicit bindings
A service name alone does not establish cleanup coverage. Inspect its artifact kinds and before-build mode: registered source versions, ordinary manual releases, managed final images, download caches and shared builder cache have different requirements. The operator installs fixed current-path, systemd and readiness bindings; callers cannot supply commands or new filesystem paths through MCP.
Manual observations bind the entire serving path and image set. The first observation becomes a protected installed baseline, with its real observation date. It is not a reconstructed history of successful deployments. A manual version can retire only after coordinated publication, verified readiness, unchanged complete artifacts and at least two other available verified later rollback sets. Current, baseline, pinned, unleased and unknown versions remain protected. Missing current or dependency evidence retains more history.
An operator can use the installed hostwatch-release wrapper around an explicitly reviewed local publication command. It serializes manual builders, reserves the configured build space and holds the publication lease through capture of the serving result. Existing SSH publishing that bypasses the wrapper can still be observed, but does not produce automatic deletion eligibility. No CI/CD or Git deployment trigger is added.
For fixed Python entrypoints or ELF executables, an operator may opt into bounded private code-only snapshots. These exclude sibling data, configuration and dependencies; a snapshot is not a complete application backup. Unknown historical directories stay protected and may be reported as unmeasured. Approved npm content-addressed download caches use an additional 30-day minimum and content checks; installed dependencies remain protected.
Retire proven superseded images without pruning recovery data
Managed final-image retention is a separate operator opt-in for configured source targets. A final image needs exact Hostwatch-generated names and immutable successful build and deployment evidence. The helper verifies the current serving binding and at least two available successful rollback sets in the target’s exact runtime. Missing or conflicting runtime evidence protects the history. The baseline image remains protected even when its source directory is unavailable.
Current, latest published, pinned and baseline images, unknown or unsuccessful references, external aliases, application containers and dependencies of retained images veto retirement. Before removal, fresh proof is checked under the same publisher and cleanup lease. Images are removed through the runtime without force; original operation receipts remain immutable and a separate local retirement receipt records the result.
The operator may separately configure how long proven unused intermediate builder cache is kept. A zero minimum permits completed, unreferenced build cache to retire when space is needed. The preview states this setting explicitly. Source, manual-release and final-image ages keep their own policy; current and rollback ancestors, active or uncertain writers, explicit builder base references and unknown ownership remain protected.
Local image retirement does not itself reclaim registry storage. When an operator installs a separate shared-registry target, its preview can include proven superseded untagged manifests and their unused blobs. Every enrolled server must have fresh reference coverage; active or uncertain writers and unfinished uploads block this work. Current, pinned, baseline and two usable rollback sets, remaining tagged and untagged manifests, shared dependencies, unknown repositories and unproven orphan blobs remain protected. The registry alone transitions through verified read-only maintenance; application containers and pods stay running. Writes and publication leases are restored before completion. Interrupted requests are drained and reconciled without replay. Registry maintenance runs separately from before-build cleanup.
Preview, then use the same cleanup engine
Refresh the preview and inspect eligible and protected artifacts with their reasons. Filesystem estimates and shared-layer lower bounds are different from virtual image sizes. Adding virtual image sizes overcounts shared layers. The actual result is the signed change in available filesystem space after the run, which can also reflect concurrent application writes.
A manual run requires the reviewed preview revision and a stable request identity. Changes in references invalidate the plan. Age eligibility stays bound to that reviewed snapshot, so objects reaching their minimum age during inspection wait for the next preview. A manual request can wait for an existing observer; it does not bypass another writer. The helper rechecks runtime and filesystem identities, uses an exclusive maintenance gate, removes image leaves through the runtime without force, and limits each run to 64 artifacts and about three minutes of deletion work. Inspection and individual runtime operations can add time.
Recent runs show their trigger, completion, errors and before/after availability. An interrupted attempt is recorded without replaying uncertain deletions. An uncertain deletion intent blocks further deletion until operator reconciliation. Refresh before starting a new request. When you retry the same request, its previous receipt is returned.
Use the same state through MCP
Search the operation catalog, select the exact node, then read retention_preview. Poll while scanning or running. Send advanced policy fields only when buildArtifacts is true; older agents accept the original five policy fields.
An owner can use retention_set_policy, retention_pin and retention_run with write scope, confirmation and the node’s governance policy. Pins identify observed versions, and manual cleanup requires a fresh expectedRevision and a stable requestId. Callers cannot provide filesystem paths, commands or new helper recipes.
image_jobs paginates hot and archived source, publication and deployment receipts. image_job_archive moves a completed receipt into durable history while retaining its permanent idempotency identity. The compatibility image_job_forget name now routes to that safe archive operation on supported agents. Older agents without this endpoint reject it. Archiving a receipt does not delete source, images or recovery data. No CI/CD or Git deployment trigger is installed.
search { query: "retention" }
execute { operation: "retention_preview", nodeId: "YOUR_NODE_ID", args: { refresh: true } }