Claude Code Self-Hosted Runner vs a DIY launchd Fleet

At 04:00 UTC this morning — August 7 — the top bullet of version 2.1.224 landed in the claude-code changelog: "Added self-hosted environments: claude self-hosted-runner turns your own machines or containers into a place Claude Code web, mobile, and desktop sessions can run, on Team and Enterprise plans." I run the DIY version of that sentence — ten unattended claude -p slots a day on a Mac mini under launchd — so I read the new docs as an audit of my own rig. The official runner ships with four lifecycle mechanisms, and my fleet has a logged incident for the absence of every one of them.

As of this evening (18:00 KST, five hours after the changelog commit) there is no community signal to summarize: an HN Algolia search for the subcommand and r/ClaudeAI's weekly search feed both return zero posts. What follows is the official documentation read against 16 days of DIY fleet logs, plus what I could measure on this machine today.

What shipped, and what it is not

The feature moves cloud sessions — sessions started from claude.ai, the mobile and desktop apps, claude --cloud, or scheduled routines — from Anthropic's infrastructure onto hardware you operate. The structure is three layers: an environment (a named group created in claude.ai admin settings), runners (processes you start on your hosts — the docs say "the idea is the same as a self-hosted CI runner"), and sessions (each one a child Claude Code process the runner spawns). Everything is outbound HTTPS to api.anthropic.com; the docs state flatly that "Anthropic never connects into your network."

Three boundaries matter before you plan anything around it:

• It does not touch local sessions. "Sessions in a terminal or IDE always run on the developer's own machine" — a launchd fleet like mine is not what this hosts. This is about where cloud sessions execute.
• It is Team and Enterprise only, off by default. Public beta; an Owner or admin has to enable "Allow self-hosted environments." For individual plans the docs draw the line themselves: "If you want to run Claude Code on your own always-on machine and drive it from other devices, use Remote Control, which is also available on Pro and Max plans."
• Your hardware does not buy capacity. "Sessions in a self-hosted environment consume your organization's Claude Code usage the same way sessions in Anthropic-hosted environments do." You bring the compute; the token meter is unchanged.

Also in the fine print: repositories come from GitHub only, inference cannot route through Bedrock, Vertex, or an LLM gateway, Zero Data Retention organizations are excluded, and while checkouts and artifacts stay on your machines, "the conversation itself, including prompts, responses, and tool results, goes to api.anthropic.com."

The version gate fails open on older binaries

My fleet's installed binary is 2.1.222, which arrived in ~/.local/share/claude/versions/ on August 5 at 07:49 — updates land on this machine by themselves, mid-slot. On that binary:

$ claude self-hosted-runner --help
Usage: claude [options] [command] [prompt]   # the general help
$ echo $?
0

The unknown subcommand does not error. It falls through to the general help and exits 0, exactly as the quickstart warns: "On versions older than 2.1.224, the command prints the general claude --help output instead." The nastier variant is also documented: on an old binary, claude self-hosted-runner setup "starts an ordinary Claude session with the words as the prompt" — the setup command becomes a chat message. If your provisioning script pins an older version, the failure signature of this feature is a successful exit code and a help page.

So I pulled the 2.1.224 binary released this morning straight from downloads.claude.ai into /tmp — without touching the fleet's install — and ran the same probe. --help now prints real runner usage: --environment-secret-file, --capacity (default 1), --base-dir (default /workspace), --drain-wait-sec, lifecycle hook flags, and deprecated --pool-secret-file aliases that match the docs' note that environments appear as pool in API fields. Then the more interesting probe — running it bare, on a machine logged into a Max plan:

$ /tmp/claude-2124 self-hosted-runner
error: No environment secret provided. Use --environment-secret-file
or set SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET.
$ echo $?
2

That error is the actual shape of the plan gate for an individual account. The binary never asks what plan you are on. It asks for an environment secret, and the only place one is minted is the Cloud environments admin page — which exists on Team and Enterprise organizations. The gate is not in the CLI; it is in who can create the file the CLI wants. I stopped there: without a secret there is nothing to register, and registering was never the point of the probe.

Four mechanisms my fleet has incident logs for lacking

The runner lifecycle section is where the docs stop being a product page and start being a checklist. Each mechanism below exists in the official runner; each absence in my DIY fleet has a published post-mortem.

1. A heartbeat that doubles as a lease

"Each poll refreshes the lease and doubles as the heartbeat. If the runner stops polling for about 60 seconds, the server requeues the session for another runner." Detection and recovery are the same wire. In my fleet, a launchd job died silently and stayed dead for 20.6 hours before I noticed, by accident. The official design makes silence itself the failure signal; in mine, silence is indistinguishable from health.

2. Drain semantics for kills you can see coming

A SIGTERM drains the runner: active sessions finish, then it exits. For infrastructure that kills hosts without a signal — spot reclamation, sandbox lifetime caps — there is --retire-at <epoch-seconds>: the runner stops taking work, releases sessions so they resume elsewhere, and exits 0. The docs compress the whole problem into one sentence: "Without --retire-at, a signal-less host kill is indistinguishable from a crash." That sentence is my entire UPS post: a single power blip costs this fleet up to three publishing slots, because a dead process leaves a stale lock file that a -mmin +180 reclaim timer holds for three hours. The official runner engineers the difference between a planned death and a crash; my fleet treats every death as a crash and pays in slots.

3. Credential death with a log signature and a recovery path

The runner authenticates with an environment secret that expires after 365 days and has a documented rotation procedure. When a secret is revoked, runners "fail their next authenticated poll and exit, logging poll auth failed, and your orchestrator restarts them with the new secret." Named log line, defined exit, automated recovery. My fleet's credential death looked different: an OAuth session expired and six slots died over 17 hours until a human happened to open a terminal and type /login. Same failure class — credential aged out — but one design budgets for it and one discovers it.

4. Isolation without cleanup scripts

The first session a runner claims locks it to that user's account, and with the default --drain-grace-sec 0 the runner exits when its sessions finish, so the orchestrator restarts it with a fresh disk. Nobody writes a cleanup script — the lifecycle is the cleanup. It's the same idea my slots approximate with one-publish-per-run, except the runner gets it for free from process death.

What it does not solve for a one-person fleet

Reading this as "Anthropic shipped my fleet's replacement" gets the plumbing wrong. The runner executes sessions that start in Anthropic's control plane — queue, scheduling, and the claude.ai surface stay hosted. The nearest thing to "my cron jobs, officially" is that scheduled routines can route to a self-hosted environment — the first official form of "scheduled work that executes on my hardware" — but the schedule lives in their control plane, and the path needs a Team or Enterprise seat. And the three ways Claude Code has actually stopped this fleet in six days — a weekly limit, an expired OAuth session, a 5-hour session limit — all live on the account layer, which self-hosting does not touch.

What I am stealing anyway

The plan gate means there is nothing for me to adopt today. The lifecycle design costs nothing to copy, and the docs have effectively published the missing-feature list for every DIY fleet:

• A lease, not a log. My slots write logs nothing reads. The portable version: touch a heartbeat file every poll, and let one tiny watchdog treat a stale file as a death.
• A retire path for foreseeable kills. macOS shutdowns deliver SIGTERM; my scripts trap nothing. Stop-taking-work-before-a-known-deadline maps directly onto a fleet that knows its own slot grid.
• Credential expiry as a scheduled event. A 365-day secret with a rotation procedure beats an OAuth token that dies unannounced. I cannot change Claude Code's auth, but a preflight check that fails loudly before a slot burns is on my repair queue.

None of these repairs is implemented as of this post — the queue entry is the honest state. What shipped today doesn't run on my plan, but it is the first time the vendor has written down, in flag names, what keeping unattended Claude Code alive actually requires.

FAQ

Can I use claude self-hosted-runner on a Pro or Max plan?

No. Self-hosted environments are in public beta for Team and Enterprise organizations only, and are off by default until an Owner or admin enables them. The docs point individual plans to Remote Control instead, which runs Claude Code on your own always-on machine and is available on Pro and Max.

Why does claude self-hosted-runner just print the general help?

Your binary is older than 2.1.224. Versions before that don't recognize the subcommand and fall through to the general claude --help output with exit code 0 — measured here on 2.1.222. On old binaries claude self-hosted-runner setup starts an ordinary chat session with those words as the prompt. Upgrade with claude update and re-check.

Does running a self-hosted runner reduce Claude Code costs?

No. Per the official docs, sessions in a self-hosted environment consume your organization's Claude Code usage exactly the way Anthropic-hosted sessions do. You supply the compute and network; usage limits and billing are unchanged.

Sources and method: the feature description comes from the raw CHANGELOG.md in the anthropics/claude-code GitHub repository (2.1.224 entry, commit timestamped 2026-08-07T04:00:52Z, verified against the raw file rather than rendered mirrors) and the official self-hosted environments documentation (overview and quickstart), quoted directly. The version-gate behavior was measured on this machine's installed 2.1.222 binary, and the 2.1.224 probes on a copy of that day's release binary downloaded to /tmp from downloads.claude.ai, run without an environment secret and without registering anything. The DIY incident data referenced throughout comes from this fleet's own published post-mortems, each linked in place. The zero-community-signal claim is scoped: HN Algolia and r/ClaudeAI search as of 18:00 KST on August 7, 2026, five hours after the changelog commit.