Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/content/workspaces/ai-tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,9 @@ Claude runs in the `tmux` session named after the workspace, starting in your ho
One-time setup:

1. On claude.ai, create a self-hosted environment and copy its environment secret.
2. In the workspace, save it:
2. In the workspace, save it in `~/.claude-runner`, which the workspace creates when the setting is on. The `README.md` there has these steps, and says where the runner keeps its logs, checkouts and rescued work.

```bash
mkdir -p ~/.claude-runner
# paste the secret, press Enter, then Ctrl-D
cat > ~/.claude-runner/environment-secret
chmod 600 ~/.claude-runner/environment-secret
Expand All @@ -122,5 +121,5 @@ On every start, the runner runs in the `tmux` session `claude-runner` (`tmux att

- **Use a workspace only for the runner.** The runner rewrites `~/.gitconfig` and `~/.config/git` before every session. It can't be turned on together with remote control.
- **Concurrent sessions** (1 to 4) sets how many sessions run at once. They share the workspace's Docker daemon and DDEV, and a skill installed in `~/.claude/skills/coder-shared-workspace` tells them how to stay out of each other's way. For full isolation, use several workspaces with one session each; the same environment secret works in all of them.
- **Checkouts carry over between sessions.** A runner keeps its clones under `~/workspace/runner-<n>`, so a new session can find what an earlier one left behind. A hook in `/etc/claude-code/managed-settings.d/coder-runner.json` lists those leftover changes at the start of the session, and the skill tells Claude how to clean them up safely.
- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-<n>`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone (`git stash list`). Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them.
- **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise the Coder workspace key. Add your fork as an SSH remote, such as `git@github.com:<you>/<repo>`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account.
43 changes: 43 additions & 0 deletions freeform/modules/claude-self-hosted-runner/files/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Claude Code self-hosted runner

The workspace's "Run a Claude Code self-hosted runner" setting created this
directory. The workspace rewrites this README on every start.

## Start the runner

1. On claude.ai, create a self-hosted environment and copy its environment
secret.
2. Save the secret here:

```bash
# paste the secret, press Enter, then Ctrl-D
cat > ~/.claude-runner/environment-secret
chmod 600 ~/.claude-runner/environment-secret
```

3. Restart the workspace. The runner starts only when
`environment-secret` exists and is not empty.

## What is here

- `environment-secret`: the secret you saved. Keep it mode 600.
- `hooks/runner-<n>/post-session`: the hook that cleans runner `<n>`'s
checkouts after each session. The workspace creates it, so do not edit it.

## Find things

- Runners: `tmux attach -t claude-runner`, logs in
`/tmp/claude-runner-<n>.log`.
- Live sessions, their checkouts and unpushed commits: `claude-sessions`.
- Checkouts: `~/workspace/runner-<n>/<owner>/<repo>`.
- Work a session left uncommitted: `git stash list | grep runner-rescue` in
the checkout. Extra clones with unpushed commits are moved to
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
Both are kept for 30 days.

## Stop the runner

Turn the setting off and restart the workspace. To stop it until the next
start, run `tmux kill-session -t claude-runner`.

More: <https://docs.coder.ddev.com/workspaces/ai-tools/#claude-code-self-hosted-runner>
30 changes: 18 additions & 12 deletions freeform/modules/claude-self-hosted-runner/files/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,14 @@ since another session can start at any time.
- Each runner clones into its own directory, `~/workspace/runner-<n>/`, so
no other session uses your checkout while you work. Never change files,
branches or git state under another runner's directory.
- A runner keeps its checkouts from one session to the next, so yours can
hold what an earlier session left behind. See "Leave the checkout clean"
- A runner keeps its checkouts from one session to the next. After every
session, `claude-runner-sweep` cleans them: it stashes uncommitted changes
as `runner-rescue` stashes, removes worktrees, and moves other clones to
`~/.local/state/claude-runner-rescue/`. See "Leave the checkout clean"
below.
- If you need a second checkout of your own repository, use a worktree
next to it, not a new clone:
`git worktree add ../<repo>-<your-branch> -b <your-branch> <base>`.
Remove it with `git worktree remove` when you are done.
- Work in the checkout the runner gave you. Do not make a new clone, and
never make a worktree or clone to get around files an earlier session
left behind. If a task needs a second checkout, ask the user first.
- Put scratch files in `~/tmp/<your session id>/`, not directly in `~/tmp`.

## Leave the checkout clean
Expand All @@ -41,12 +42,17 @@ When a session starts in a checkout that is not clean, a hook prints the
changed paths. Untracked files left by another branch can break a build or
change what it generates, such as DDEV's image tags.

- At the start, run `git status`. Do not commit changes you did not make.
- Before deleting an untracked file, check that a commit holds the same
content: `git log --all --oneline -1 --find-object=$(git hash-object <file>)`.
Delete only the files this finds. Ask the user about the rest.
- Restore a tracked file only when the change is generated output, or when
the user agrees.
- If the hook reports leftovers, they are not yours. Save them, then carry
on in the same checkout:
`git stash push --include-untracked -m "leftovers from an earlier session"`.
Do not commit, delete or restore them.
- The runner can end your session without warning once the user has sent
nothing for 30 minutes. Before you finish a turn and wait for the user,
commit your work, and push it if the task includes pushing. What you
leave uncommitted is stashed when the session ends, and a resumed session
may run on another runner, in a checkout without it.
- If the hook says this session was released earlier and its changes were
saved, tell the user what was saved before restoring any of it.
- At the end, delete the branches, worktrees and stashes you created, and
leave `git status` clean.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,20 +1,31 @@
#!/usr/bin/env bash
# Claude Code SessionStart hook, installed by the claude-self-hosted-runner
# module. A runner keeps its checkouts from one session to the next, so tell
# a new session when an earlier one left changes behind. Usage:
# module. A runner keeps its checkouts from one session to the next, and
# claude-runner-sweep cleans them after each session. Tell a new session when
# that did not happen, and tell a resumed one where the sweep put its work.
# Usage:
# claude-checkout-check <runner base dir>
# Prints nothing for a clean checkout or one outside the base dir, such as a
# project you run claude in by hand.
base="${1:?usage: claude-checkout-check <runner base dir>}"
rescue_root="${CLAUDE_RUNNER_RESCUE_DIR:-$HOME/.local/state/claude-runner-rescue}"
dir="${CLAUDE_PROJECT_DIR:-$PWD}"
case "$dir/" in
"${base%/}"/*) ;;
*) exit 0 ;;
esac
# The hook's input names this session; the sweep logs the runner's ids for it.
input=$(cat 2>/dev/null)
sid=$(jq -r '.session_id // empty' <<<"$input" 2>/dev/null)
if [ -n "$sid" ] && [ -f "$rescue_root/log" ] && grep -qF -- "$sid" "$rescue_root/log"; then
echo "This session was released earlier, and the runner saved what it had left uncommitted. Entries in $rescue_root/log:"
grep -F -- "$sid" "$rescue_root/log" | tail -10
echo "Stashes are in the checkout named there (find them with: git -C <checkout> stash list | grep runner-rescue). Before restoring one, tell the user what it holds."
fi
status=$(git -C "$dir" status --porcelain 2>/dev/null) || exit 0
[ -n "$status" ] || exit 0
count=$(printf '%s\n' "$status" | wc -l)
echo "The checkout $dir is not clean at the start of this session: an earlier session left $count changed or untracked path(s)."
echo "They are not part of your task, and they can break a build. Before you build, test or commit, follow \"Leave the checkout clean\" in the coder-shared-workspace skill."
echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\". Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill."
printf '%s\n' "$status" | head -20
[ "$count" -le 20 ] || echo "... and $((count - 20)) more"
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,21 @@ export GIT_CONFIG_GLOBAL="$base/.gitconfig"
# forwarded agent when one is connected, otherwise the Coder workspace key.
# Without it, sessions can't push to an SSH remote such as a fork.
export SSH_AUTH_SOCK="$HOME/.ssh-agent-relay/agent.sock"
# The runner keeps its checkouts between sessions. Its post-session hook cleans
# them (claude-runner-sweep), and so does this loop before every start, for a
# runner that was killed before its hook ran, as when the workspace stops.
hooks="$HOME/.claude-runner/hooks/runner-$n"
mkdir -p "$hooks"
printf '#!/usr/bin/env bash\nexec "$HOME/.local/bin/claude-runner-sweep" %q\n' "$base" >"$hooks/post-session"
chmod +x "$hooks/post-session"
while true; do
"$HOME/.local/bin/claude-runner-sweep" "$base"
started=$(date +%s)
/home/linuxbrew/.linuxbrew/bin/claude self-hosted-runner \
--environment-secret-file "${secret_file}" \
--base-dir "$base" \
--hooks-dir "$hooks" \
--post-session-hook-timeout-sec 120 \
--capacity 1 \
--client-label "$CODER_WORKSPACE_NAME-$n" \
--use-anthropic-git-proxy \
Expand Down
131 changes: 131 additions & 0 deletions freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
#!/usr/bin/env bash
# Installed by the claude-self-hosted-runner module. Cleans one runner's
# checkouts after a session, so the next session starts clean. Usage:
# claude-runner-sweep <runner dir, such as ~/workspace/runner-1>
# Runs as the runner's post-session hook and before every runner start, so
# never while a session uses the directory (each runner has --capacity 1).
# Nothing a session left is deleted unless a commit or remote already holds it:
# - Leftover changes in the runner's clones go into a "runner-rescue" stash.
# - Worktrees are removed, after stashing their changes the same way.
# - Other clones, and broken worktrees, are deleted if they hold nothing
# unpushed, and otherwise moved to the rescue directory,
# ~/.local/state/claude-runner-rescue/<runner>/<time>/.
# Every action is logged in the rescue directory's "log". Rescue stashes and
# directories older than CLAUDE_RUNNER_RESCUE_DAYS (default 30) are removed.
set -u
runner_dir="${1:?usage: claude-runner-sweep <runner dir>}"
runner_dir="${runner_dir%/}"
[ -d "$runner_dir" ] || exit 0
runner=$(basename "$runner_dir")
rescue_root="${CLAUDE_RUNNER_RESCUE_DIR:-$HOME/.local/state/claude-runner-rescue}"
keep_days="${CLAUDE_RUNNER_RESCUE_DAYS:-30}"
stamp=$(date +%Y%m%d-%H%M%S)
session="${CLAUDE_RUNNER_SESSION_ID:-no-session}"
uuid="${CLAUDE_RUNNER_SESSION_UUID:-}"
mkdir -p "$rescue_root"
# Lifecycle hooks may run git without the session's identity; a stash needs one.
export GIT_AUTHOR_NAME="${GIT_AUTHOR_NAME:-Claude runner}" GIT_AUTHOR_EMAIL="${GIT_AUTHOR_EMAIL:-noreply@anthropic.com}"
export GIT_COMMITTER_NAME="${GIT_COMMITTER_NAME:-Claude runner}" GIT_COMMITTER_EMAIL="${GIT_COMMITTER_EMAIL:-noreply@anthropic.com}"

note() {
printf '%s %s %s %s %s\n' "$(date -Is)" "$runner" "$session" "${uuid:--}" "$*" >>"$rescue_root/log"
echo "claude-runner-sweep: $*"
}

dirty() { [ -n "$(git -C "$1" status --porcelain 2>/dev/null)" ]; }

# Stash everything uncommitted in a checkout, including untracked files. A
# merge, rebase or cherry-pick in progress blocks a stash, so abort it first;
# its commits are still on the branch it started from.
rescue_stash() {
local dir="$1" what="$2" branch msg
dirty "$dir" || return 0
branch=$(git -C "$dir" branch --show-current 2>/dev/null)
branch="${branch:-detached at $(git -C "$dir" rev-parse --short HEAD 2>/dev/null)}"
msg="runner-rescue $stamp $session $what on $branch"
if ! git -C "$dir" stash push --include-untracked --quiet -m "$msg" >/dev/null 2>&1; then
local op
for op in merge rebase cherry-pick revert; do
git -C "$dir" "$op" --abort >/dev/null 2>&1 && note "aborted an unfinished $op in $dir"
done
dirty "$dir" || return 0
if ! git -C "$dir" stash push --include-untracked --quiet -m "$msg" >/dev/null 2>&1; then
note "FAILED to stash changes in $dir; left in place"
return 1
fi
fi
note "stashed changes in $dir as \"$msg\""
}

# True when deleting this checkout loses nothing: no changes, no stashes and
# no commits that are missing from every remote-tracking branch.
disposable() {
local dir="$1"
git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || return 1
dirty "$dir" && return 1
[ -z "$(git -C "$dir" stash list 2>/dev/null)" ] || return 1
[ "$(git -C "$dir" rev-list --count --branches --not --remotes 2>/dev/null)" = 0 ] || return 1
# A detached HEAD may hold commits on no branch at all.
[ -z "$(git -C "$dir" rev-list -1 HEAD --not --remotes --branches 2>/dev/null)" ] || return 1
}

# The runner clones <owner>/<repo> into <runner dir>/<owner>/<repo>. Anything
# else at that depth with a .git is a clone or worktree a session made.
is_runner_clone() {
local dir="$1" url name
[ -d "$dir/.git" ] || return 1
url=$(git -C "$dir" remote get-url origin 2>/dev/null) || return 1
name=$(basename "${url%/}" .git)
[ "$name" = "$(basename "$dir")" ]
}

shopt -s nullglob
candidates=()
for dir in "$runner_dir"/*/*/; do
dir="${dir%/}"
case "$dir" in
"$runner_dir"/_sessions/* | "$runner_dir"/.*) continue ;;
esac
[ -e "$dir/.git" ] && candidates+=("$dir")
done

# Runner clones first, so their worktrees are gone before the second pass.
for dir in "${candidates[@]}"; do
is_runner_clone "$dir" || continue
while read -r wt; do
[ "$wt" = "$dir" ] && continue
if [ -d "$wt" ]; then
rescue_stash "$wt" "worktree $(basename "$wt")" || continue
if git -C "$dir" worktree remove --force "$wt" 2>/dev/null; then
note "removed worktree $wt"
fi
fi
done < <(git -C "$dir" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
git -C "$dir" worktree prune 2>/dev/null
rescue_stash "$dir" "checkout"
# Drop expired rescue stashes, highest index (oldest) first, so the lower
# indexes stay valid.
cutoff=$(($(date +%s) - keep_days * 86400))
git -C "$dir" stash list --format='%gd %ct %gs' 2>/dev/null | sort -t'{' -k2 -rn |
while read -r ref ct subject; do
case "$subject" in *runner-rescue*) ;; *) continue ;; esac
[ "$ct" -lt "$cutoff" ] && git -C "$dir" stash drop --quiet "$ref" 2>/dev/null
done
done

for dir in "${candidates[@]}"; do
[ -e "$dir" ] || continue
is_runner_clone "$dir" && continue
if disposable "$dir"; then
rm -rf "$dir" && note "deleted $dir, which held nothing unpushed"
else
dest="$rescue_root/$runner/$stamp/$(basename "$(dirname "$dir")")"
mkdir -p "$dest" && mv "$dir" "$dest/" && note "moved $dir to $dest/"
fi
done

find "$rescue_root" -mindepth 2 -maxdepth 2 -type d -mtime +"$keep_days" -exec rm -rf {} + 2>/dev/null
if [ -f "$rescue_root/log" ] && [ "$(wc -l <"$rescue_root/log")" -gt 5000 ]; then
tail -n 2000 "$rescue_root/log" >"$rescue_root/log.tmp" && mv "$rescue_root/log.tmp" "$rescue_root/log"
fi
exit 0
2 changes: 2 additions & 0 deletions freeform/modules/claude-self-hosted-runner/main.tf
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ locals {
managed_settings = jsonencode({
hooks = {
SessionStart = [{
# Not "compact" or "clear": by then the changes are the session's own.
matcher = "startup|resume"
hooks = [{
type = "command"
command = "/home/coder/.local/bin/claude-checkout-check ${var.base_dir}"
Expand Down
8 changes: 7 additions & 1 deletion freeform/modules/claude-self-hosted-runner/outputs.tf
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,14 @@ output "startup_script" {
CLAUDE_RUNNER_ENABLED="${local.enabled}"
CLAUDE_REMOTE_CONTROL_ENABLED="${var.remote_control_enabled}"
if [ "$CLAUDE_RUNNER_ENABLED" = "true" ]; then
# Created before the checks below, so the secret has an obvious home.
mkdir -p ~/.claude-runner
chmod 700 ~/.claude-runner
echo '${base64encode(file("${path.module}/files/README.md"))}' | base64 -d > ~/.claude-runner/README.md
if [ "$CLAUDE_REMOTE_CONTROL_ENABLED" = "true" ]; then
CLAUDE_RUNNER_MSG="✗ Claude Code self-hosted runner NOT started: Claude Code remote control is also enabled, and the runner rewrites ~/.gitconfig before every session. Turn one of them off."
elif [ ! -s "${local.secret_file}" ]; then
CLAUDE_RUNNER_MSG="✗ Claude Code self-hosted runner NOT started: save your environment secret as ${local.secret_file} (chmod 600), then restart the workspace."
CLAUDE_RUNNER_MSG="✗ Claude Code self-hosted runner NOT started: save your environment secret as ${local.secret_file} (chmod 600), then restart the workspace. See ~/.claude-runner/README.md."
else
# /etc is not persistent, so reinstall the session git config on every start.
echo '${base64encode(file("${path.module}/files/gitconfig"))}' | base64 -d | sudo tee /etc/gitconfig >/dev/null
Expand All @@ -29,6 +33,8 @@ output "startup_script" {
chmod +x ~/.local/bin/claude-sessions
echo '${base64encode(file("${path.module}/files/claude-checkout-check"))}' | base64 -d > ~/.local/bin/claude-checkout-check
chmod +x ~/.local/bin/claude-checkout-check
echo '${base64encode(file("${path.module}/files/claude-runner-sweep"))}' | base64 -d > ~/.local/bin/claude-runner-sweep
chmod +x ~/.local/bin/claude-runner-sweep
sudo mkdir -p /etc/claude-code/managed-settings.d
echo '${base64encode(local.managed_settings)}' | base64 -d | sudo tee /etc/claude-code/managed-settings.d/coder-runner.json >/dev/null
mkcert -install >/dev/null 2>&1 || true
Expand Down
Loading
Loading