Run a Claude Code self-hosted runner

Before you start#

• A Claude Team or Enterprise plan. Self-hosted environments are in public beta there, and off until an Owner turns on Allow self-hosted environments on the Cloud environments admin page.
• GitHub connected: the GitHub connector turned on by an Owner, and your own GitHub account connected on claude.ai, as for any cloud session. The runner fetches and pushes your code through Anthropic, so the VM needs no GitHub credentials.
• The Claude GitHub App installed on the repositories Claude should push to, by someone who administers their GitHub organization. Without it, sessions can clone public repositories but can't push.
• An environment and its key. On the Cloud environments page, under Self-hosted environments, select New, name it (say exe-dev), and select Create. On the next step, select Copy environment key. claude.ai shows the key only once.

Set up the runner#

Deploy sets it up on a new VM and asks for the environment key and the account it serves. To do it yourself:

ssh exe.dev new --name=my-claude-code-runner
ssh my-claude-code-runner.exe.xyz

sudo useradd --create-home --shell /bin/bash claude-runner
sudo -iu claude-runner bash -c 'curl -fsSL https://claude.ai/install.sh | bash'
sudo -iu claude-runner claude self-hosted-runner --help | head -3

sudo -u claude-runner ln -sf /usr/local/bin/uv /usr/local/bin/uvx /home/claude-runner/.local/bin/

sudo install -d -m 755 /etc/claude
sudo install -m 600 -o claude-runner -g claude-runner /dev/null /etc/claude/environment-secret
sudo -u claude-runner sh -c 'cat > /etc/claude/environment-secret'

echo 'SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT=you@example.com' | sudo tee /etc/claude/runner.env

sudo -u claude-runner mkdir -p /home/claude-runner/.claude
sudo -u claude-runner tee /home/claude-runner/.claude/CLAUDE.md > /dev/null <<EOF
This session runs on $(hostname), an exe.dev VM.

- To show the user a web app, listen on 0.0.0.0 on a port from 3000 to
  9999 other than 8080, and give them https://$(hostname).exe.xyz:<port>/.
  Only the VM's owner, and people they share it with, can open it.
- Commit and push your work before you finish a task. A session that sits
  idle for an hour is released and resumes from a fresh checkout.
EOF

sudo tee /etc/systemd/system/claude-runner.service > /dev/null <<'EOF'
[Unit]
Description=Claude Code self-hosted runner
Wants=network-online.target
After=network-online.target

[Service]
User=claude-runner
WorkingDirectory=/home/claude-runner
Environment=PATH=/home/claude-runner/.local/bin:/usr/local/go/bin:/usr/sbin:/usr/bin:/sbin:/bin
EnvironmentFile=-/etc/claude/runner.env
ExecStart=/home/claude-runner/.local/bin/claude self-hosted-runner \
  --environment-secret-file /etc/claude/environment-secret \
  --base-dir /home/claude-runner/work \
  --use-anthropic-git-proxy --configure-git \
  --release-idle-session-min 60 --kill-session-after-min 480 \
  --remove-session-state
Restart=always
RestartSec=15
KillMode=mixed
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now claude-runner
sleep 10; journalctl -u claude-runner -n 20 --no-pager | grep -E 'Registered|fatal'

Start a session on your VM#

Open claude.ai/code, pick a GitHub repository, and choose your environment (exe-dev) in the environment picker, where it sits beside Anthropic's. The desktop app lists it under Cloud, and the Code tab of the mobile app has the same picker. Try:

Run hostname, then add a hello.py that prints the date.

Claude answers with the VM's name. The runner's log shows the pickup:

ssh my-claude-code-runner.exe.xyz journalctl -u claude-runner -n 30 --no-pager | grep 'Picked up session'

From a terminal, run /remote-env in Claude Code once and pick the environment. After that, claude --cloud "<task>" from a checkout of a GitHub repository sends the task to your VM.

One runner serves one session at a time. A session keeps the runner until you archive it, or until it has been idle for an hour, when the runner releases it. Your next message resumes it on a fresh checkout, so work Claude hadn't pushed is gone; the CLAUDE.md above asks Claude to push. A session that runs eight hours is released the same way. Other sessions wait in the environment's queue meanwhile. For more at once, see More runners.

See what Claude builds#

When a session starts a web app on a port from 3000 to 9999, open it at https://my-claude-code-runner.exe.xyz:<port>/. exe.dev's HTTPS proxy keeps those addresses private to you and anyone you share the VM with. Port 8080 is the runner's own health check.

To look around the machine, SSH in. Checkouts are under /home/claude-runner/work/<owner>/<repo>:

ssh my-claude-code-runner.exe.xyz 'sudo ls /home/claude-runner/work'

Give sessions your tools#

Sessions run as claude-runner, without sudo, and inherit the service's environment. To prepare the machine:

• System packages. As exedev, sudo apt-get install what your builds need. Sessions use it from then on.
• Docker. Sessions can't use Docker until you add the runner to the docker group. That is as good as root on the VM, so do it only if you need it: sudo usermod -aG docker claude-runner && sudo systemctl enable --now docker.service && sudo systemctl restart claude-runner.
• MCP servers and settings. Run claude mcp add --scope user ... as claude-runner (sudo -iu claude-runner), or edit its ~/.claude/settings.json. The runner reads them when it starts, so restart it afterwards.
• Internal services. Sessions reach whatever the VM reaches, including services you connect through exe.dev integrations, with no keys on the VM.

Warning

Sessions run model-directed commands without asking first, and every session on this VM can read the environment key in /etc/claude/environment-secret, with which anyone could register a runner in your environment. Keep this VM for the runner, put nothing on it you wouldn't hand to Claude, and rotate the key on claude.ai if a session goes wrong. Anthropic's hardening checklist covers production fleets.

More runners#

For more sessions at once, or a runner for each person, copy the VM. On your computer:

ssh exe.dev cp my-claude-code-runner my-claude-code-runner-2

The copy registers as a runner of its own, named after the VM, with the same key, tools, and account lock. For a teammate, set their email in /etc/claude/runner.env on the copy and run sudo systemctl restart claude-runner. Copies share your plan's CPU and memory. Remove one with ssh exe.dev rm my-claude-code-runner-2.

Update#

The runner, and every session it starts, runs the Claude Code installed for claude-runner. A new model can require a newer version. To update, on the VM, while no session is running:

sudo -iu claude-runner claude update
sudo systemctl restart claude-runner

Restarting stops a running session's turn. The session resumes on your next message.

Back up#

The runner keeps little of its own: your code lives in GitHub, and conversations on claude.ai. What matters is the environment key, which claude.ai won't show again, so keep it in your password manager. Without it, create a new key on the environment's Configuration tab, write it to /etc/claude/environment-secret, restart the runner, and revoke the old one. Keys expire 365 days after they are created.

To keep the whole machine, with its tools and settings, copy it as in More runners, and stop the copy's runner with sudo systemctl disable --now claude-runner until you need it.

Troubleshooting#

The runner's log is journalctl -u claude-runner on the VM:

• RegisterRunner auth failed: the environment key is wrong, revoked, or expired. Fix /etc/claude/environment-secret and restart.
• cannot create or write to base directory: /home/claude-runner/work isn't the runner's. Run sudo chown -R claude-runner: /home/claude-runner.
• The session stays queued: the runner is serving another session, or is locked to another account. Check for Picked up session in the log and the email in /etc/claude/runner.env; archive sessions you're done with, or add a runner.
• GitHub authentication required: the person who started the session hasn't connected GitHub on claude.ai, or the connection expired.
• A push fails with Claude doesn't have GitHub access to <owner>/<repo>: the Claude GitHub App isn't installed on that repository. A GitHub organization admin installs it at github.com/apps/claude; then ask Claude to push again in the same session.
• the server withheld Anthropic-managed git for this session: one of the session's repositories isn't on github.com. See the FAQ.
• This model needs a newer version of Claude Code: update.

For a guided diagnosis, sign the runner user in with sudo -iu claude-runner claude auth login, then run sudo -iu claude-runner claude self-hosted-runner doctor. Anthropic's troubleshooting guide covers the rest.