Run the server

Free disk space

See what the worktrees use, make room by archiving or abandoning items or from Settings › Storage, and set a limit with automatic clean-up.

Each work item gets a git worktree in run/worktrees/<item id>/, a full checkout of its repo, plus any dependencies its setup command installed. That adds up.

Before you start

  • $KRAFT_HOME is ~/.kraft unless you set it; see Environment variables. The commands find run/ as Kraft does: $KRAFT_RUN_DIR when you set it, else run/ under $KRAFT_HOME.
  • Deleting old session logs needs the server stopped. If Kraft runs as a service, stop it as Stop a service says.

Reclaim disk space

  1. See what uses space:
    run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}"
    du -sh "$run"/*
    

    With storage.worktrees.limit set, kraft view storage lists the worktrees item by item instead. kraft item archive --reclaimable archives every finished one, after showing what each loses.
  2. Remove the worktrees you no longer need. A worktree is removed when its item is abandoned or archived:
    • Abandon a work item you no longer want: kraft item abandon ID --reason "..." --yes. It removes the worktree, deletes the item's local branch, and removes its folder in run/items/ (and an older item's attachment copies in run/attachments/). Uncommitted work is lost, and so are commits you never pushed.
    • Archive a completed or abandoned item from the board's Done group, with kraft item archive ID (it previews first and needs --yes), or with POST /api/work-items/ID/archive. It removes the worktree, the sandbox home and the step outputs, and keeps the item's record, documents, session logs and attachment copies, so you can still read and duplicate it. Commit uncommitted changes in the worktree first, or copy them out from kraft repo open ID: archiving loses them.
    • Auto-archive. archive.after_days in policy.yaml archives completed and abandoned items that old. The shipped file sets 30. Lower it to reclaim space sooner. See policy.yaml.
  3. Delete an archived item's folder, run/items/<item id>/, by hand, with the server stopped, to drop its documents and session files. Sessions from before one folder per item left their logs in run/logs/ and result files in run/results/; delete those the same way. All of them stay after archiving.

You know it worked when du -sh "$run"/* shows worktrees smaller, and ls "$run/worktrees" no longer lists the item.

What archive does to the branch

  • It deletes the local branch only when every commit on it is somewhere else too: another branch such as the base, a remote-tracking branch, a tag or what Kraft pushed. Otherwise the branch stays, and the archive event says how many commits it kept.
  • Commits on a detached HEAD in the worktree are kept on a new branch, kraft/rescued/<item id>. If Kraft can't make that branch, it archives the item but leaves the worktree, and the archive event's worktree_kept says why.

An in-place item's archive deletes no folder, and keeps its branch when it holds commits nowhere else or when the checkout is on it: see Abandon or archive an in-place item.

kraft item complete and kraft item cancel keep the worktree until the item is archived. A cancelled item that never pushed keeps its branch after that too. Delete it by hand once you are done with it: git branch -D <branch>.

Clean up from the Storage page

Added in 2.1

Use Settings › Storage when worktrees are over the limit, or when you want the space back.

  1. Open Settings › Storage and tick the finished items you want to free, or take them all with Clean up all.
  2. Press Clean up selected or Clean up all, read the confirmation, then press Clean up N items and free X. The confirmation lists the uncommitted files each item loses.

Each item moves to Archived, and what archiving removes and keeps is as Reclaim disk space says. Held starts go within seconds. Storage describes the bar, the rows and the other controls. From a shell, kraft view storage prints the same breakdown and kraft item archive --reclaimable archives after showing the same confirmation.

You know it worked when the bar drops below the limit and the archived rows leave the list.

Saved copies of a repo's carry files sit in run/carried/, outside the quota.

Limit the disk worktrees use

Added in 2.1

Without a limit, worktrees use disk until you notice. Set one in policy.yaml and Kraft tells you before the disk is full, and holds new starts at the limit:

config/policy.yaml
storage:
  worktrees:
    limit: 10G
    quota: 8G   # optional; defaults to 80% of limit

Run kraft admin reload to apply it, or edit Settings › Policy › Housekeeping › Storage. A size is a whole number and a unit, such as 10G. Over quota Kraft warns. Over limit it holds starts that need a new worktree, and the instance reads degraded. Storage keys has the size format, what counts toward each and the rest.

See where you stand:

kraft admin doctor
kraft admin health

Over the limit, make room in any of these ways, then wait about 10 seconds for the queue to start what is held:

  • Archive finished items, from Settings › Storage or the board's Done group, as Reclaim disk space describes. Archiving removes the worktree and any uncommitted changes in it, keeps a branch with unpushed commits, and leaves the item restorable under Archived.
  • Finish or abandon live work.
  • Raise limit.

A start that is held shows as queued with work_item_storage_held on its timeline. An item that already has its worktree is never held, so finishing it is always possible.

You know it worked when kraft admin doctor reports the storage line as ok, and a held item leaves queued.

An item that runs in place has no worktree, so the limit never measures, holds or archives it.

Let Kraft make room

An instance left running unattended can sit held with nobody to clean up. Add auto_cleanup and Kraft archives finished items itself when worktrees pass the limit:

config/policy.yaml
storage:
  worktrees:
    limit: 10G
    auto_cleanup:
      min_age: 24h   # the default; the block being there is what turns it on

Over limit, Kraft archives completed and abandoned items that ended at least min_age ago, oldest first, until usage is at or under quota. It needs a limit, and Storage keys has the rules.

If every finished item is newer than min_age, nothing is archived and starts stay held. kraft admin doctor then says how many were too recent, and you make room as above. If an item's documents keep usage over the limit, the server log names it and the Storage page shows them under Documents; abandoning that item removes them.

You know it ran when an item's timeline has work_item_archived with reason: storage, and the Archived view shows it as archived by auto.

Next steps

Copyright © 2026