Self-hosted environments quickstart changedself-hosted-environments-quickstart
Nearest release: v2.1.309, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Oct 2026 19:29 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+22added
Lines−22removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55> [!NOTE]
66>
7> Self-hosted environments are in public beta on Team and Enterprise plans; [Availability and limitations](/docs/en/self-hosted-environments#availability-and-limitations) covers the enablement path. This page gets your first session running; see [Self-hosted environments](/docs/en/self-hosted-environments) for what they are and [Deploy to production](/docs/en/self-hosted-environments-deploy.md) for hardening and fleet recipes.
7> Self-hosted environments are in public beta on Team and Enterprise plans; [Availability and limitations](https://code.claude.com/docs/en/self-hosted-environments#availability-and-limitations) covers the enablement path. This page gets your first session running; see [Self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments) for what they are and [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md) for hardening and fleet recipes.
88
9A [self-hosted environment](/docs/en/self-hosted-environments) runs Claude Code [cloud sessions](/docs/en/claude-code-on-the-web.md) on infrastructure your organization operates, executed by runner processes you deploy. This quickstart stands up your first one, the smallest that works: one runner on a single host, running one test session. There are two steps: [create the environment, start a runner, and route a session to it](#set-up-an-environment-and-runner), then [message that session from your terminal](#send-a-follow-up-message-to-a-running-session). You'll move between two surfaces: claude.ai for creating the environment, checking its status, and routing a session, and a terminal on the host for everything the runner does.
9A [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) runs Claude Code [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) on infrastructure your organization operates, executed by runner processes you deploy. This quickstart stands up your first one, the smallest that works: one runner on a single host, running one test session. There are two steps: [create the environment, start a runner, and route a session to it](#set-up-an-environment-and-runner), then [message that session from your terminal](#send-a-follow-up-message-to-a-running-session). You'll move between two surfaces: claude.ai for creating the environment, checking its status, and routing a session, and a terminal on the host for everything the runner does.
1010
11By the end you'll have an environment on the [**Cloud environments** admin page](https://claude.ai/admin-settings/cloud-environments), a runner polling for work, and a session running on your host. Before you connect real repositories or internal systems, work through [Deploy to production](/docs/en/self-hosted-environments-deploy.md), which covers the security posture, egress control, git credentials, and orchestration.
11By the end you'll have an environment on the [**Cloud environments** admin page](https://claude.ai/admin-settings/cloud-environments), a runner polling for work, and a session running on your host. Before you connect real repositories or internal systems, work through [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md), which covers the security posture, egress control, git credentials, and orchestration.
1212
1313## Prerequisites
1414
from line 16
1616
1717The claude.ai side needs:
1818
19* **Allow self-hosted environments** turned on by an [Owner](/docs/en/cloud-environments.md#organization-shared-environments) on the [**Cloud environments** admin page](https://claude.ai/admin-settings/cloud-environments); the **New** button doesn't appear until it is. If you don't hold the role, someone who does can create the environment and hand you its secret; the runner and terminal steps on this page need no claude.ai role, and where a step checks status in the admin UI, the runner's own log lines give you the same signal.
20* The [GitHub connector](https://claude.ai/admin-settings/connectors) turned on by an Owner, and each developer's own [GitHub connection](/docs/en/web-quickstart.md#connect-github), so they can pick github.com repositories when they start sessions.
19* **Allow self-hosted environments** turned on by an [Owner](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) on the [**Cloud environments** admin page](https://claude.ai/admin-settings/cloud-environments); the **New** button doesn't appear until it is. If you don't hold the role, someone who does can create the environment and hand you its secret; the runner and terminal steps on this page need no claude.ai role, and where a step checks status in the admin UI, the runner's own log lines give you the same signal.
20* The [GitHub connector](https://claude.ai/admin-settings/connectors) turned on by an Owner, and each developer's own [GitHub connection](https://code.claude.com/docs/en/web-quickstart.md#connect-github), so they can pick github.com repositories when they start sessions.
2121
2222### Host and network
2323
2424The runner host needs:
2525
26* A Linux or macOS host or container with outbound HTTPS to `api.anthropic.com`, to `claude.ai` and the download hosts it redirects to for the install step below, and to your git host for the clone; the [network requirements table](/docs/en/self-hosted-environments-deploy.md#network-requirements) has the full list. Windows isn't supported as a runner host; run the runner in a Linux container instead. Developer workstations aren't affected, since sessions start from claude.ai in a browser.
27* A repository for the test session: a public one, or one this host can already clone by its HTTPS URL without being asked for credentials. An SSH key alone isn't enough, because the runner clones the repository's `https://` URL. To clone over SSH instead, see [Rewrite git URLs for private networks](/docs/en/self-hosted-environments-deploy.md#rewrite-git-urls-for-private-networks).
28* A clock synchronized to real time, for example with NTP. Authentication fails when the clock is more than five minutes off; see [Troubleshooting](/docs/en/self-hosted-environments-deploy.md#troubleshooting).
26* A Linux or macOS host or container with outbound HTTPS to `api.anthropic.com`, to `claude.ai` and the download hosts it redirects to for the install step below, and to your git host for the clone; the [network requirements table](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#network-requirements) has the full list. Windows isn't supported as a runner host; run the runner in a Linux container instead. Developer workstations aren't affected, since sessions start from claude.ai in a browser.
27* A repository for the test session: a public one, or one this host can already clone by its HTTPS URL without being asked for credentials. An SSH key alone isn't enough, because the runner clones the repository's `https://` URL. To clone over SSH instead, see [Rewrite git URLs for private networks](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#rewrite-git-urls-for-private-networks).
28* A clock synchronized to real time, for example with NTP. Authentication fails when the clock is more than five minutes off; see [Troubleshooting](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#troubleshooting).
2929
3030### Software on the runner host
3131
3232Install on the host before you start:
3333
34* **Claude Code v2.1.224 or later**, with any of the [standard install methods](/docs/en/setup.md). The runner is part of the standard `claude` binary, and earlier versions don't recognize the `self-hosted-runner` subcommand. To pin the exact version your fleet runs, see [Install a specific version](/docs/en/setup.md#install-a-specific-version). For container images, see the Dockerfile in [Deploy to production](/docs/en/self-hosted-environments-deploy.md#build-the-runner-image).
35* **Git 2.24 or newer**. Some git options on the deploy page need newer versions; [Configure git](/docs/en/self-hosted-environments-deploy.md#configure-git) states each floor.
34* **Claude Code v2.1.224 or later**, with any of the [standard install methods](https://code.claude.com/docs/en/setup.md). The runner is part of the standard `claude` binary, and earlier versions don't recognize the `self-hosted-runner` subcommand. To pin the exact version your fleet runs, see [Install a specific version](https://code.claude.com/docs/en/setup.md#install-a-specific-version). For container images, see the Dockerfile in [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#build-the-runner-image).
35* **Git 2.24 or newer**. Some git options on the deploy page need newer versions; [Configure git](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#configure-git) states each floor.
3636
3737Confirm the host is ready:
3838
from line 40
4040claude self-hosted-runner --help
4141```
4242
43A ready host prints the runner's usage text, listing flags such as `--environment-secret-file`. On versions older than 2.1.224, the command prints the general `claude --help` output instead. If you see that output, [update Claude Code](/docs/en/setup.md#update-claude-code). If you run `claude` from a container image, [rebuild the image](/docs/en/self-hosted-environments-deploy.md#build-the-runner-image) with version 2.1.224 or later.
43A ready host prints the runner's usage text, listing flags such as `--environment-secret-file`. On versions older than 2.1.224, the command prints the general `claude --help` output instead. If you see that output, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code). If you run `claude` from a container image, [rebuild the image](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#build-the-runner-image) with version 2.1.224 or later.
4444
4545## Set up an environment and runner
4646
from line 67
6767
6868**1. Create an environment**
6969
70Go to the [**Cloud environments** page](https://claude.ai/admin-settings/cloud-environments) in admin settings. Under **Self-hosted environments**, select **New**, name the environment, and select **Create**. On the wizard's second step, select **Copy environment key** to copy the environment secret, which the admin UI labels an environment key. claude.ai shows the secret once, and you can't retrieve it later; it expires 365 days after creation. The environment's `ccpool_...` ID stays visible in its detail dialog; you'll need it for the `aud` check in [token verification](/docs/en/self-hosted-environments-identity.md) and for dispatching [test sessions from CI](/docs/en/self-hosted-environments-testing.md#run-the-test-loop).
70Go to the [**Cloud environments** page](https://claude.ai/admin-settings/cloud-environments) in admin settings. Under **Self-hosted environments**, select **New**, name the environment, and select **Create**. On the wizard's second step, select **Copy environment key** to copy the environment secret, which the admin UI labels an environment key. claude.ai shows the secret once, and you can't retrieve it later; it expires 365 days after creation. The environment's `ccpool_...` ID stays visible in its detail dialog; you'll need it for the `aud` check in [token verification](https://code.claude.com/docs/en/self-hosted-environments-identity.md) and for dispatching [test sessions from CI](https://code.claude.com/docs/en/self-hosted-environments-testing.md#run-the-test-loop).
7171
7272If you lose the secret or need to rotate it, create a new secret from the environment's **Configuration** tab, roll the new secret out to your runners, then revoke the old one. Runners holding a revoked secret fail their next authenticated poll and exit, logging `poll auth failed`, and your orchestrator restarts them with the new secret.
7373
from line 91
9191>
9292> Use a directory dedicated to the runner, not your home directory or a directory of your own clones. The runner treats whatever it finds at `<writable-dir>/<repo-owner>/<repo>` as its own clone, and can reset it and overwrite or delete files in it.
9393
94If the runner can't create or write to the base directory, it exits at startup with an error naming the directory instead of registering. See [Troubleshooting](/docs/en/self-hosted-environments-deploy.md#troubleshooting).
94If the runner can't create or write to the base directory, it exits at startup with an error naming the directory instead of registering. See [Troubleshooting](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#troubleshooting).
9595
9696Then start the runner with `--environment-secret-file` and `--base-dir`:
9797
from line 113
113113
114114If the session doesn't start working, match what you see:
115115
116* **The session sits queued**: see [Troubleshooting](/docs/en/self-hosted-environments-deploy.md#troubleshooting).
116* **The session sits queued**: see [Troubleshooting](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#troubleshooting).
117117* **The session fails to start with a git error**: if the error includes git's `could not read Username for` followed by your git host's URL, the runner had no HTTPS credentials for that host.
118 * **Supply HTTPS credentials**: see [Configure git](/docs/en/self-hosted-environments-deploy.md#configure-git)
119 * **Clone over SSH instead**: if the runner host already has an SSH key, see [Rewrite git URLs for private networks](/docs/en/self-hosted-environments-deploy.md#rewrite-git-urls-for-private-networks)
118 * **Supply HTTPS credentials**: see [Configure git](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#configure-git)
119 * **Clone over SSH instead**: if the runner host already has an SSH key, see [Rewrite git URLs for private networks](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#rewrite-git-urls-for-private-networks)
120120
121121### If the runner exits
122122
123123If the runner exits during this quickstart, start it again. The runner can exit on its own:
124124
125* **Nothing left running**: the log shows `[runner:exit] account workload drained — exiting`. The runner [exits by design](/docs/en/self-hosted-environments#runner-lifecycle) once it's no longer running any session, for example:
125* **Nothing left running**: the log shows `[runner:exit] account workload drained — exiting`. The runner [exits by design](https://code.claude.com/docs/en/self-hosted-environments#runner-lifecycle) once it's no longer running any session, for example:
126126 * **You archived or deleted the session**: start the runner again
127127 * **The session failed to start**: [fix the cause](#session-doesnt-start), then start the runner again
128128* **Lost contact**: the log shows a `[runner:fatal]` line with `runner record gone server-side` or with `poll auth failed`. If the runner loses contact with Anthropic for a while, for example because the host sleeps, it can exit when it next reaches Anthropic.
from line 129
129129
130130A finished turn doesn't end your test session. After the first turn the session is still attached and the runner is still up, so you can [send the session a follow-up message](#send-a-follow-up-message-to-a-running-session) without restarting the runner first.
131131
132For production, deploy the runner under an orchestrator that restarts it on exit and waits longer between restarts when the runner keeps exiting right after it starts. See [Deploy to production](/docs/en/self-hosted-environments-deploy.md) and [When the runner exits](/docs/en/self-hosted-environments-deploy.md#when-the-runner-exits).
132For production, deploy the runner under an orchestrator that restarts it on exit and waits longer between restarts when the runner keeps exiting right after it starts. See [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md) and [When the runner exits](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#when-the-runner-exits).
133133
134134## Send a follow-up message to a running session
135135
from line 139
139139claude -p "your message" --cloud <session-id>
140140```
141141
142For `<session-id>`, pass the bare `session_...` or `cse_...` ID or the session's claude.ai/code URL. A successful send prints `Sent to cloud session.` with the session ID and a view link. Accepted ID forms, JSON output, and the account and policy requirements are on [Send follow-ups from the CLI](/docs/en/claude-code-on-the-web.md#send-follow-ups-from-the-cli), since the command works the same against Anthropic-hosted sessions.
142For `<session-id>`, pass the bare `session_...` or `cse_...` ID or the session's claude.ai/code URL. A successful send prints `Sent to cloud session.` with the session ID and a view link. Accepted ID forms, JSON output, and the account and policy requirements are on [Send follow-ups from the CLI](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-follow-ups-from-the-cli), since the command works the same against Anthropic-hosted sessions.
143143
144144## What's next
145145
146* [Deploy to production](/docs/en/self-hosted-environments-deploy.md): harden the deployment, control egress, configure git credentials, and run the fleet under Kubernetes or Compose
147* [Customize sessions](/docs/en/self-hosted-environments-configuration.md): wrapper scripts, lifecycle hooks, on-demand runners, MCP servers, and permissions
148* [Test end to end](/docs/en/self-hosted-environments-testing.md): a CI smoke test that dispatches a session and reads Claude's replies
146* [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md): harden the deployment, control egress, configure git credentials, and run the fleet under Kubernetes or Compose
147* [Customize sessions](https://code.claude.com/docs/en/self-hosted-environments-configuration.md): wrapper scripts, lifecycle hooks, on-demand runners, MCP servers, and permissions
148* [Test end to end](https://code.claude.com/docs/en/self-hosted-environments-testing.md): a CI smoke test that dispatches a session and reads Claude's replies
149149
No line in this hunk matches that.