Managed worktrees

Agents that edit code need somewhere to work. Doing that inside the repository you are also using means two writers on one index, and temporary directories that outlive the task. Managed worktrees give each task its own branch and checkout, recorded in the shared state database, outside the source repository. When the task ends, the contents are snapshotted before anything is removed, so an abandoned checkout is recoverable rather than lost.

Where checkouts live

• By default OpenClaw stores managed checkouts in a worktrees folder inside the state directory, and a global option can point them at another folder or disk using an absolute path on the Gateway host or a path inside the Gateway user home directory, while relative paths are rejected.
• Each checkout sits under a repository fingerprint made from the first 16 hexadecimal characters of a SHA-256 hash over the canonical git common directory and the origin URL, and a supplied name must match a lowercase pattern of at most 64 characters, otherwise OpenClaw generates a readable crustacean-themed name such as brisk-lobster.
• OpenClaw creates a branch named after the worktree at the requested base ref, and without one it fetches origin, uses the remote default branch when available, and falls back to local HEAD when the repository is offline or has no usable remote.
• Every checkout added during creation or snapshot restore has a five-minute timeout, including a creation retry from local HEAD, while other managed-worktree git commands keep a two-minute timeout and the optional repository setup script keeps its own two-minute limit.

Ignored files never enter the repository object database.

Disk space and capacity

OpenClaw treats 100 live managed worktrees per state directory as a cleanup target rather than an admission cap, so count alone never blocks creation or snapshot restore. Available disk space still bounds new allocations, and creation never evicts another session to make room. Before allocating a checkout, OpenClaw checks its destination, git metadata, source checkout and state volumes. It keeps ten per cent of each volume free, with a minimum reserve of 4 GiB and a maximum of 16 GiB, plus twice the estimated git checkout and provisioned-file size. A validated reusable source template replaces the full checkout allowance with an estimate for clone metadata and index writes, while cold templates and every native git fallback require the full allowance again immediately before allocation. An executable setup script requires additional room equal to the larger of 4 GiB or the current source checkout footprint excluding git metadata. Space is checked again before provisioning and setup, and once more after setup. These are conservative estimates rather than a quota, because shell commands, deployment tools and build output can still consume the same volume. Snapshot removal uses a smaller reserve of 128 MiB plus estimated snapshot writes, so safe cleanup remains possible below the operational reserve.

Acceleration and templates

• OpenClaw uses filesystem acceleration automatically for new managed worktrees where it is supported, with native Btrfs snapshots on Linux, an APFS directory clone on macOS that preserves file contents, executable modes and symbolic links, and ReFS block clones on Windows including Dev Drive volumes.
• One reusable source-only template is kept per repository and destination root, rebuilt when the requested commit or checkout policy changes, and cleanup retires templates that have gone unused for seven days.
• Templates hold checked-out source only, so provisioning of ignored files and the repository setup script still run separately for each new worktree under their existing permissions, and neither dependencies nor setup output are shared through the template.

A worktree is only useful next to the rest of the agent setup: the Agent workspaces it is anchored to, and the Sessions that own it. A session-owned worktree is used by every agent run in that session, and deleting the session snapshots and removes the checkout.

Why removal is careful

Cleanup has to assume that an abandoned checkout still contains work nobody has pushed. That is why removal first creates a synthetic commit of tracked and non-ignored untracked files and pins it under a snapshot ref, and why a failed snapshot stops the removal unless an explicit force delete discards that safety. At run end a worktree is removed only when the status is clean and no unpushed commits remain, otherwise OpenClaw simply releases the activity lock. Startup and hourly cleanup then snapshot and remove unlocked Workboard-owned and session-owned worktrees idle for more than seven days, even when dirty, while manual worktrees are never removed automatically. The same caution shapes what runs inside a new checkout: Command execution of the repository setup script is limited to an admin-scoped caller, and repository hooks and filesystem monitors are always disabled, which matters when the agent itself runs in a Sandboxing. Snapshot records stay restorable for 30 days before the ref and the registry row are deleted.

On Diali

Diali runs Hosted OpenClaw on Diali for you, one assistant per customer, with the runtime configuration generated from the dashboard and replaced at each release. State lives on a persistent volume, so the work an agent leaves behind is still there after an upgrade; daily snapshots and one-click restore are available through the Backups add-on (included on Max). Plan details are on Diali pricing.

• Each task gets its own branch and checkout, outside the source repository.
• Removal snapshots first, and snapshots stay restorable for 30 days.
• Disk checks, not a worktree count, are what bound new allocations.