Data retention
How long the harness keeps tasks, how to delete them, put them under a legal hold, or keep no content at all with zero-retention.
Each environment has data settings: how long finished tasks are kept, whether their content is erased as soon as they end, and whether everything is held.
hexel harness settings
hexel harness settings set --retention-days 90
hexel harness settings set --zero-retention=true
hexel harness settings set --legal-hold=trueGET /harness/environments/settings and PUT /harness/environments/settings read and change them; a field you leave out keeps its value. Changing them needs harness:environment:admin (Admins and Owners).
| Setting | Default | Description |
|---|---|---|
retention_days | 30 | Finished tasks are deleted this many days after they last changed. 1 to 3650. |
zero_retention | false | Erase a task's content in the runtime as soon as it ends. |
legal_hold | false | Hold the whole environment: nothing is pruned or deleted. |
delete_artifacts | false | Not available yet (409 artifact_deletion_unavailable): artifacts stay in your storage. |
Retention
Every minute, finished tasks (succeeded, failed, cancelled, budget_exhausted) that last changed more than retention_days ago, and are not held, are deleted as if you had deleted them. A member of a swarm that is still open is kept until later.
Delete a task
hexel harness task delete tsk_123DELETE /harness/tasks/{id} removes the task and everything under it from the control plane in one step and answers 202 with {task_id, erasures}: one erasure for each runtime that holds its runs, which then erases what it holds. GET /harness/erasures (hexel harness erasures) lists the environment's erasures with their state: pending, done or failed. The task's own event stream ends with the task.
- A task under a legal hold cannot be deleted (
409 legal_hold). - A fork is a task of its own: it is not deleted with its parent. A fork of the task that has not started yet fails (
parent_erased). - A task whose runs never reached a runtime has one erasure,
doneat once.
What is erased
On the private preview's hosted runtime, each run's erasure is carried out by a step of its own in your organization's runner pool. It stops what is left of the run, destroys its sandboxes, erases its sessions, drops the run's own storage (its ledger and job queue), and erases the task's records and its task-scoped memory. The erasure is then done, and its result reads {"sessions": <n>, "artifacts": "kept"}.
An erasure that cannot finish yet stays pending with its last reason in failed_reason, and is tried again until it is done.
What stays
- Artifacts stay in your storage: the result says
"artifacts": "kept", anddelete_artifactsis not available yet. - Titan's records of the task's sessions stay in your organization's Titan: their Agent Ledger and Session Store entries, which hold ids, digests and decisions, and no harness content in the default metadata-only data mode.
- A sandbox the erasure could not reach is not destroyed by it: it ends at its timeout (one hour), and the result counts it in
sandboxes_left_to_timeout. - A board swarm's shared content goes with the erasure of a member task when the swarm is no longer running and no task of it is left. It stays in the runner pool when the swarm's last task is deleted while the swarm is still running, or when the last task deleted never ran on the hosted runtime. This is a known gap.
Legal hold
hexel harness task hold tsk_123
hexel harness task hold tsk_123 --releasePUT /harness/tasks/{id}/hold {"hold": true} holds one task (held_at on the task); legal_hold in the settings holds the whole environment. A held task is never pruned, cannot be deleted, and its content is never erased by zero-retention. A hold that answered 200 applies to every deletion after it. Holding a task whose content is already being erased is refused (409 erasure_in_progress).
Zero-retention
In a zero-retention environment, when a task ends, the runtime erases its runs' sessions and kept outputs, and the control plane then removes the task's goal, inputs and command content. The task's stream gets task.erased {scope: "content", by: "zero_retention"}, and the task shows erased_at.
- What stays: ids, states, costs, digests and sizes, and in the runtime the run ids, Titan approval ids and artifact digests. Artifacts stay in your storage.
- Turning zero-retention on needs the metadata-only data mode, the default (
409 zero_retention_unavailableotherwise). - A task that ran out of budget is not erased, since a resume continues it.
- An erased task cannot be retried or resumed (
409 task_erased), forked (409 parent_zero_retention), or used byinputs_from(409 inputs_from_unavailable). - A swarm member's output kept for its reduce step or lead stays until the swarm's task is deleted.