Skip to content
← Back to release · 2.1.268
New features / v2.1.268

Delete session state on exit

CHANGELOG · original

Added claude self-hosted-runner --remove-session-state (default off): delete each session's per-session directories under <base-dir>/_sessions/ when the session ends
Open official changelog ↗

Documentation

Documentation excerpt

Reuse a pre-warmed checkout

For large repositories, the clone can dominate session startup. To skip the cold clone, supply a clone yourself at the path where the runner keeps its own. With no checkout hook, the runner keeps one canonical clone per repository at <base-dir>/<repo-owner>/<repo> and reuses it across sessions:

  • At --capacity 1: the runner fetches the requested ref, detaches HEAD, and resets hard to it, which is near-instant when little has changed.
  • At a --capacity above one: the runner fetches into that clone, then checks out a separate worktree from it for each session. A pre-warmed clone saves the download but not the checkout.

Supply the clone in the image or on a persistent volume:

  • Clone in the image: build the clone into your runner image at that path. Every fresh container then starts with the warm clone without reusing a disk.
  • Clone on a persistent volume: on runners you pre-lock to one user's account with --lock-to-account, point --base-dir at a persistent volume, so the disk only ever serves that account. A pre-locked runner never picks up Claude Tag channel sessions, so this option doesn't apply to runners that serve them.

To use a clone outside --base-dir, pass its real path to --repository-folder at --capacity 1, such as --repository-folder acme/api=/volumes/warm/api. The runner resets the clone's tracked files for each session. Give each runner its own copy, at the same path on every runner. Start each runner on a fresh copy, or pre-lock a fixed-fleet runner with --lock-to-account.

What the reuse path does and doesn't guarantee:

  • Clone depth: build the clone without --depth, with or without --single-branch. The runner never passes --depth when it fetches into a clone with an origin remote, even if you set CLAUDE_RUNNER_FETCH_DEPTH. With a full clone, each session downloads only the commits the clone lacks. With a shallow clone, a session on a branch that forked before the clone's oldest commit downloads that branch's whole history.

  • Tracked changes reset, untracked files persist: at --capacity 1, each session starts from a hard reset that wipes the previous session's tracked modifications, but the runner never runs git clean, so untracked files from the locked owner's earlier sessions stay in the tree.

  • Per-session directories persist too: alongside the checkout, the runner creates per-session entries under <base-dir>/_sessions/ for every session it runs. The session's Claude config directory holds a local copy of the conversation transcript. Next to it sit the session's uploaded files, when the session has any. The session directory sits there too: it holds any per-session worktrees and checkout hook checkouts while the session runs, and it keeps whatever else Claude wrote in it.

    By default the runner leaves these in place when the session ends, so on a disk that outlives the runner process they accumulate. Every session runs as the runner's own user, so any later session that disk serves can read them. If you keep a persistent --base-dir, size the volume for that growth. The same applies to any setup that restarts the runner on the same filesystem, including the Docker Compose recipe.

  • With --remove-session-state, per-session directories don't persist: start the runner with --remove-session-state to have it delete each session's per-session directories as the session ends. The deletion is best-effort: the directories stay when the runner is killed before its cleanup runs. The canonical clone and files a session wrote elsewhere on the host, such as the temporary directory, stay regardless.

  • With the git proxy, the reset becomes a checkout: with --use-anthropic-git-proxy, the runner sanitizes the clone's .git/ before each session. It keeps the object store and shallow state, and deletes the index. Without the index, each session starts with a full working-tree checkout instead of a near-instant reset. The runner still fetches into the existing clone rather than cloning the repository again. Submodule pre-warms aren't supported under the proxy.

  • With the git proxy, a reftable pre-warm loses its refs: when the runner sanitizes .git/ before each session, it keeps .git/refs/ and removes the .git/reftable/ directory. A clone pre-warmed in git's reftable ref format loses its refs that way, so pre-warm the clone in git's files ref format instead.

  • Long clones need no workaround: the runner bounds each git operation with a 120-second no-progress watchdog and a 30-minute hard cap, not a flat timeout, so a slow cold clone that keeps reporting progress completes.

Confirm that the runner uses your clone

To confirm that the runner uses your clone, start it with --log-level debug and start a session on the repository. The runner logs Prefetched repo found at and the clone's path. If it logs No prefetched repo, fresh init at instead, it found no usable clone at the path in that line. Check that your clone is at that path, owned by the runner's user, with a remote named origin.

If the runner finds your clone and sessions still start slowly, check whether the clone is shallow.

Documentation snapshot · 2026-11-20

Change details