pks agentics runner cleanup

Restarting the runner strands its containers. Each spawned container is bound to the runner process that created it through a pks.agentics.runner-instance label, and its bind mounts point at temp directories the new process does not share — so the old containers can never be reused. runner cleanup finds them and removes them.

1. Prerequisites

• The docker CLI on PATH with a reachable daemon. If listing containers fails, the command aborts with exit code 1 rather than reporting zero containers.
• No confusion about scope. This removes containers, not volumes and not remote containers. A runner handed off over SSH keeps its containers on the remote machine.

2. See what would go

Always start with a dry run.

pks agentics runner cleanup --dry-run

The command lists every container carrying the pks.agentics.fingerprint label, running or stopped, and marks which ones it considers orphaned.

3. Understand the liveness heuristic

There is no out-of-band registry of live runner-instance ids, so liveness is approximated: the command looks for a running pks-cli agentics runner start process with pgrep.

• No runner process running — every labelled container is treated as an orphan and becomes a removal candidate.
• A runner process running — the check cannot tell which instance it belongs to, so it stays conservative: only label-less containers are treated as orphans, and anything carrying a runner-instance label is left alone even if it is stale.

4. Remove the orphans

pks agentics runner cleanup

You are asked Remove N container(s)?, defaulting to No, then each candidate is removed with docker rm -f. To skip the prompt in a script:

pks agentics runner cleanup --yes

5. Remove everything, deliberately

--all bypasses the liveness heuristic and removes every pks.agentics.* container regardless of whether a runner is using it — including a container a running runner may reuse for a warm or in-flight job.

pks agentics runner cleanup --all --dry-run

Confirm the list first, then re-run without --dry-run.

6. Verify

docker ps -a --filter label=pks.agentics.fingerprint

You should see only containers belonging to a runner you intend to keep.

Options

Troubleshooting

• Exit code 1 with a listing failure. Docker is not installed or the daemon is down. Fix Docker, then re-run.
• Nothing is removed while a runner is running. That is the conservative branch of the heuristic. Stop the runner and re-run, or use --all after checking a dry run.
• A stale container survives repeated cleanups. It carries a runner-instance label and a runner process is live. Stop the runner first.
• Containers reappear after every restart. Expected — each restart orphans the previous instance's containers. Add a cleanup to your restart routine.

See also

• Start the Agentics runner daemon — the process whose restarts create orphans
• pks agentics runner — how the runner lifecycle fits together
• pks agentics CLI reference — every flag and environment variable