Self-hosted environments quickstart - Claude Code Docs

A self-hosted environment runs Claude Code cloud sessions 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, then message that session from your terminal. 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. By the end you’ll have an environment on the Cloud environments admin page, 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, which covers the security posture, egress control, git credentials, and orchestration.

Prerequisites

Organization and roles

The claude.ai side needs:

Allow self-hosted environments turned on by an Owner on the Cloud environments admin page; 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.
A GitHub connection for your organization, so developers can pick repositories when they start sessions.

Host and network

The runner host needs:

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 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.
A clock synchronized to real time, for example with NTP. Authentication fails when the clock is more than five minutes off; see Troubleshooting.

Software on the runner host

Install on the host before you start:

Claude Code v2.1.224 or later, with any of the standard install methods. The runner is part of the standard claude binary, and earlier versions don’t recognize the self-hosted-runner subcommand. The native installer’s default latest channel carries each release as soon as it’s published; the stable channel, the Homebrew claude-code cask, and the stable apt, dnf, and apk repositories trail by about a week. To pin the exact version your fleet runs, see Install a specific version. For container images, see the Dockerfile in Deploy to production.
Git 2.24 or newer. Some git options on the deploy page need newer versions; Configure git states each floor.

Confirm the host is ready:

A 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; upgrade with claude update or reinstall from the latest channel.

Set up an environment and runner

Claude Code includes a guided setup: an interactive Claude Code session that walks you through creating the environment in the admin UI, starts a local runner with the secret file you save, confirms that the runner registers, and writes a cheat sheet to ./runner-setup/CHEAT-SHEET.md. Run it on a machine where you’ve signed in with claude auth login using an account that holds an Owner role; it isn’t available with API keys or third-party model providers. On hosts where an interactive session isn’t possible, use the manual steps below instead. Confirm the version check passed first: on versions older than 2.1.224, this command starts an ordinary Claude session with the words as the prompt instead of the guided setup. To start the guided setup, run the setup subcommand and follow the prompts:

To set up manually instead:

The runner exits by design once its active sessions finish; see Runner lifecycle. For production, deploy it under an orchestrator that restarts it on exit. See Deploy to production.

Send a follow-up message to a running session

Once a session is running on your environment, send it a follow-up from the claude CLI on any machine where you’re logged in with claude auth login; the command doesn’t need to run from the machine that started the session. The command posts one message:

For <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, the account and policy requirements, and the error reference are on Send follow-ups from the CLI, since the command works the same against Anthropic-hosted sessions.

What’s next

Deploy to production: harden the deployment, control egress, configure git credentials, and run the fleet under Kubernetes or Compose
Customize sessions: wrapper scripts, lifecycle hooks, on-demand runners, MCP servers, and permissions
Test end to end: a CI smoke test that dispatches a session and reads Claude’s replies