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
29 changes: 27 additions & 2 deletions docs/content/workspaces/ai-tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,31 @@ One-time setup:
On every start, the runner runs in the `tmux` session `claude-runner` (`tmux attach -t claude-runner`), logging to `/tmp/claude-runner-<n>.log`. Sessions clone their repositories under `~/workspace/runner-<n>`. Run `claude-sessions` to list live sessions with their checkout, branch and number of unpushed commits.

- **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.
- **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 (see [Who can use the runner](#who-can-use-the-runner)).
- **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.
- **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 your Coder 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. The runner adds GitHub's host keys to `~/.ssh/known_hosts`. SSH pushes act as the workspace owner, whoever started the session; see [Who acts on GitHub](#who-acts-on-github).

### Who acts on GitHub

The runner uses Anthropic-managed git. A session reaches GitHub in four ways. Two of them act as the account that started the session, and two act as you, the workspace owner:

| Path | Acts as |
|---|---|
| HTTPS git: the clone, fetch, and pushes to `origin` | The GitHub account connected to the claude.ai account that started the session |
| The GitHub MCP tools in a session | The same connected account, through Anthropic's proxy |
| `gh` | Whoever is logged in to `gh` in the workspace: you, after `gh auth login`. Without a login, `gh` doesn't work. |
| SSH remotes (`git@github.com:…`) | Every key in the workspace SSH agent: the workspace owner's forwarded agent, or the owner's Coder key |

- **Connect GitHub** in claude.ai, under **Settings → Connectors → GitHub**. Nothing in the workspace stands in for it. When the connection is missing or has expired, the session fails before Claude starts, and `/tmp/claude-runner-<n>.log` shows `Repository access validation failed` with `GitHub authentication required. Please reconnect your GitHub account.` Reconnect, then start the session again. Until then the runner exits and restarts after each attempt, and the session may be retried on other runners.
- **Log in to `gh` once in the workspace** with `gh auth login`. Sessions then use your login for `gh`, with GraphQL and every repository you can reach. Without a login, sessions use the GitHub MCP tools, which reach only the repositories attached to the session.
- **Tell Claude to use `gh`.** Claude's built-in instructions in a runner session prefer the GitHub MCP tools, and use `gh` only when your own instructions name it. Add a line such as "Use `gh` for GitHub operations; it is logged in as me." to `~/.claude/CLAUDE.md`. The runner copies `~/.claude` into every session.
- **Your Coder key is the same in all your workspaces.** `coder publickey` prints one key per Coder user, so adding it to GitHub lets SSH push as you from every runner workspace you own, for every session on it.
- **SSH offers every key the agent holds.** With an agent forwarded from your computer, sessions can sign with all of its keys, not only your GitHub key, for as long as you stay connected.

### Who can use the runner

**A runner workspace is personal. Don't share its environment.** An environment is a pool: every runner that uses its secret, in this workspace or any other, takes the next session from anyone who can start sessions in that environment. The runner's label decides nothing.

- A session from another person would run as your Unix user, with your SSH agent, your Coder key, and any credentials stored in the workspace. Its SSH pushes would act as you, and no template setting can prevent that: any process in a workspace can use the owner's Coder key, through `coder gitssh` or the workspace agent.
- Each person who wants a runner creates their own environment and their own runner workspace.
- Use a separate environment for each kind of runner you want to choose between, for example one per operating system. Sessions go to whichever runner is free, with no routing by label or platform.
36 changes: 36 additions & 0 deletions freeform/modules/claude-self-hosted-runner/files/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,42 @@ directory. The workspace rewrites this README on every start.
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
Both are kept for 30 days.

## GitHub access

Sessions clone, fetch and push to `origin` over HTTPS as the GitHub account
connected to the claude.ai account that started them, under Settings →
Connectors on claude.ai. Every person who starts sessions here needs that
connection. The GitHub MCP tools in a session use the same account. A
session started without a repository gets no clone and no GitHub MCP tools.

`gh` in a session is this workspace's own `gh`. Run `gh auth login` here
once, and sessions use your login, with GraphQL and every repository you
can reach. Then add a line such as "Use `gh` for GitHub operations; it is
logged in as me." to `~/.claude/CLAUDE.md`, because sessions use `gh` only
when your instructions say so. Without a login, sessions use the GitHub MCP
tools, which reach only the repositories attached to the session.

SSH remotes use this workspace's SSH agent: your forwarded agent, or your
Coder key, which is the same in all your workspaces. SSH pushes act as you
in every session. The workspace adds GitHub's host keys to
`~/.ssh/known_hosts` on start.

This runner is personal. Every runner that uses this environment secret
takes sessions from anyone who can start sessions in the environment, and
runs them as you, with your SSH agent and Coder key. Don't share the
environment with other people.

## Troubleshooting

- A session fails before Claude starts, and the log shows
`Repository access validation failed` and `GitHub authentication
required. Please reconnect your GitHub account.`: the person who started
the session must reconnect GitHub on claude.ai, then start the session
again. Until then each runner that picks it up exits and restarts, which
is expected.
- `gh` in a session says it isn't logged in: run `gh auth login` in the
workspace, or let sessions use the GitHub MCP tools.

## Stop the runner

Turn the setting off and restart the workspace. To stop it until the next
Expand Down
31 changes: 26 additions & 5 deletions freeform/modules/claude-self-hosted-runner/files/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,19 +127,40 @@ only what you created (build output, your worktrees, your `~/tmp`
directory, your test projects). Never delete another session's files, and
never prune Docker images or volumes another session may use.

## GitHub and `gh`

HTTPS git (the clone, fetch, and pushes to `origin`) and the GitHub MCP
tools act as the GitHub account connected to the claude.ai account that
started this session, through Anthropic's proxy. The MCP tools reach only
the repositories attached to the session.

`gh` here is the workspace's own `gh`, and acts as whoever logged it in,
normally the workspace owner.

- Run `gh auth status`. With a login, `gh` works fully, GraphQL included,
for every repository that account can reach. Use it when the user's
instructions say to.
- Without a login, use the GitHub MCP tools. Don't report the missing
login as a problem, and don't run `gh auth login` or set `GH_TOKEN`
yourself; that is the user's decision.

## Pushing over SSH

`SSH_AUTH_SOCK` points at the workspace SSH agent relay,
`~/.ssh-agent-relay/agent.sock`. The relay uses the user's own agent when
one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses the Coder
workspace key, which GitHub accepts once the user adds it to their account
(`coder publickey` prints it).
`~/.ssh-agent-relay/agent.sock`. The relay uses the workspace owner's own
agent when one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses
the owner's Coder key, which GitHub accepts once the owner adds it to
their account (`coder publickey` prints it). SSH pushes act as the
workspace owner, who may not be the person who started this session.

- When you add a remote, such as the user's fork, use its SSH URL:
`git remote add <name> git@github.com:<owner>/<repo>`. HTTPS pushes go
through the session's git proxy, which reaches only the repositories
attached to the session.
- Leave `origin` as the runner cloned it.
- `ssh -T git@github.com` greets the user by name when SSH works.
- `ssh -T git@github.com` greets the account SSH pushes act as. Compare it
with the account the MCP tools report (`get_me`), or with
`gh api user --jq .login` when `gh` has a login. If they differ, or you
have neither to compare, ask the user before pushing over SSH.
- On `Permission denied (publickey)`, ask the user to forward an agent or
add the Coder key to GitHub. Never create, copy or print keys.
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
7 changes: 7 additions & 0 deletions freeform/modules/claude-self-hosted-runner/outputs.tf
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ output "startup_script" {
# The runner copies ~/.claude into each session when it starts.
mkdir -p ~/.claude/skills/coder-shared-workspace ~/.cache "${var.base_dir}"
echo '${base64encode(file("${path.module}/files/SKILL.md"))}' | base64 -d > ~/.claude/skills/coder-shared-workspace/SKILL.md
# Without github.com in known_hosts, SSH pushes from sessions fail with
# "Host key verification failed". These are GitHub's published keys.
mkdir -p ~/.ssh
chmod 700 ~/.ssh
if ! ssh-keygen -F github.com >/dev/null 2>&1; then
echo '${base64encode(file("${path.module}/files/github_known_hosts"))}' | base64 -d >> ~/.ssh/known_hosts
fi
mkdir -p ~/.local/bin
echo '${base64encode(local.loop_script)}' | base64 -d > ~/.local/bin/claude-runner-loop
chmod +x ~/.local/bin/claude-runner-loop
Expand Down
4 changes: 4 additions & 0 deletions freeform/tests/validate.tftest.hcl
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,10 @@ run "claude_runner_enabled" {
condition = strcontains(base64decode(regex("echo '([A-Za-z0-9+/=]+)' \\| base64 -d > ~/.local/bin/claude-runner-loop", coder_agent.main.startup_script)[0]), "--capacity 1")
error_message = "each runner must use --capacity 1, which --use-anthropic-git-proxy requires"
}
assert {
condition = strcontains(base64decode(regex("echo '([A-Za-z0-9+/=]+)' \\| base64 -d >> ~/.ssh/known_hosts", coder_agent.main.startup_script)[0]), "github.com ssh-ed25519 ")
error_message = "startup script must add GitHub's host keys to known_hosts, or SSH pushes from sessions fail host key verification"
}
assert {
condition = strcontains(base64decode(regex("echo '([A-Za-z0-9+/=]+)' \\| base64 -d \\| sudo tee /etc/claude-code/managed-settings.d/coder-runner.json", coder_agent.main.startup_script)[0]), "claude-checkout-check /home/coder/workspace")
error_message = "startup script must install the SessionStart hook that reports a checkout left dirty by an earlier session"
Expand Down
36 changes: 36 additions & 0 deletions modules/claude-self-hosted-runner/files/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,42 @@ directory. The workspace rewrites this README on every start.
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
Both are kept for 30 days.

## GitHub access

Sessions clone, fetch and push to `origin` over HTTPS as the GitHub account
connected to the claude.ai account that started them, under Settings →
Connectors on claude.ai. Every person who starts sessions here needs that
connection. The GitHub MCP tools in a session use the same account. A
session started without a repository gets no clone and no GitHub MCP tools.

`gh` in a session is this workspace's own `gh`. Run `gh auth login` here
once, and sessions use your login, with GraphQL and every repository you
can reach. Then add a line such as "Use `gh` for GitHub operations; it is
logged in as me." to `~/.claude/CLAUDE.md`, because sessions use `gh` only
when your instructions say so. Without a login, sessions use the GitHub MCP
tools, which reach only the repositories attached to the session.

SSH remotes use this workspace's SSH agent: your forwarded agent, or your
Coder key, which is the same in all your workspaces. SSH pushes act as you
in every session. The workspace adds GitHub's host keys to
`~/.ssh/known_hosts` on start.

This runner is personal. Every runner that uses this environment secret
takes sessions from anyone who can start sessions in the environment, and
runs them as you, with your SSH agent and Coder key. Don't share the
environment with other people.

## Troubleshooting

- A session fails before Claude starts, and the log shows
`Repository access validation failed` and `GitHub authentication
required. Please reconnect your GitHub account.`: the person who started
the session must reconnect GitHub on claude.ai, then start the session
again. Until then each runner that picks it up exits and restarts, which
is expected.
- `gh` in a session says it isn't logged in: run `gh auth login` in the
workspace, or let sessions use the GitHub MCP tools.

## Stop the runner

Turn the setting off and restart the workspace. To stop it until the next
Expand Down
31 changes: 26 additions & 5 deletions modules/claude-self-hosted-runner/files/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,19 +127,40 @@ only what you created (build output, your worktrees, your `~/tmp`
directory, your test projects). Never delete another session's files, and
never prune Docker images or volumes another session may use.

## GitHub and `gh`

HTTPS git (the clone, fetch, and pushes to `origin`) and the GitHub MCP
tools act as the GitHub account connected to the claude.ai account that
started this session, through Anthropic's proxy. The MCP tools reach only
the repositories attached to the session.

`gh` here is the workspace's own `gh`, and acts as whoever logged it in,
normally the workspace owner.

- Run `gh auth status`. With a login, `gh` works fully, GraphQL included,
for every repository that account can reach. Use it when the user's
instructions say to.
- Without a login, use the GitHub MCP tools. Don't report the missing
login as a problem, and don't run `gh auth login` or set `GH_TOKEN`
yourself; that is the user's decision.

## Pushing over SSH

`SSH_AUTH_SOCK` points at the workspace SSH agent relay,
`~/.ssh-agent-relay/agent.sock`. The relay uses the user's own agent when
one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses the Coder
workspace key, which GitHub accepts once the user adds it to their account
(`coder publickey` prints it).
`~/.ssh-agent-relay/agent.sock`. The relay uses the workspace owner's own
agent when one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses
the owner's Coder key, which GitHub accepts once the owner adds it to
their account (`coder publickey` prints it). SSH pushes act as the
workspace owner, who may not be the person who started this session.

- When you add a remote, such as the user's fork, use its SSH URL:
`git remote add <name> git@github.com:<owner>/<repo>`. HTTPS pushes go
through the session's git proxy, which reaches only the repositories
attached to the session.
- Leave `origin` as the runner cloned it.
- `ssh -T git@github.com` greets the user by name when SSH works.
- `ssh -T git@github.com` greets the account SSH pushes act as. Compare it
with the account the MCP tools report (`get_me`), or with
`gh api user --jq .login` when `gh` has a login. If they differ, or you
have neither to compare, ask the user before pushing over SSH.
- On `Permission denied (publickey)`, ask the user to forward an agent or
add the Coder key to GitHub. Never create, copy or print keys.
3 changes: 3 additions & 0 deletions modules/claude-self-hosted-runner/files/github_known_hosts
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
7 changes: 7 additions & 0 deletions modules/claude-self-hosted-runner/outputs.tf
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ output "startup_script" {
# The runner copies ~/.claude into each session when it starts.
mkdir -p ~/.claude/skills/coder-shared-workspace ~/.cache "${var.base_dir}"
echo '${base64encode(file("${path.module}/files/SKILL.md"))}' | base64 -d > ~/.claude/skills/coder-shared-workspace/SKILL.md
# Without github.com in known_hosts, SSH pushes from sessions fail with
# "Host key verification failed". These are GitHub's published keys.
mkdir -p ~/.ssh
chmod 700 ~/.ssh
if ! ssh-keygen -F github.com >/dev/null 2>&1; then
echo '${base64encode(file("${path.module}/files/github_known_hosts"))}' | base64 -d >> ~/.ssh/known_hosts
fi
mkdir -p ~/.local/bin
echo '${base64encode(local.loop_script)}' | base64 -d > ~/.local/bin/claude-runner-loop
chmod +x ~/.local/bin/claude-runner-loop
Expand Down
Loading