Self-hosted environments reference - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Self-hosted environments are in public beta on Team and Enterprise plans; an Owner enables them by turning on Allow self-hosted environments on the Cloud environments admin page . This page is the flag and metric reference; see the quickstart for setup and Deploy to production for the fleet recipes.
This page is the reference for the two processes you run in a self-hosted environment : the runner, which executes Claude Code cloud sessions on your hosts, and the optional autoscaling orchestrator, which starts runners as sessions queue. Each has its own flag table. Both run on Linux or macOS hosts, which the defaults such as /workspace and ~/.claude assume. Run claude self-hosted-runner --help for the authoritative list on your installed version.
Metric series and a few API fields still use pool for what these pages call an environment; both terms name the same thing. The environment ID is the pool_id field, with the form ccpool_... : wherever these pages show a pool identifier, it names the environment. CLI flags and environment variables spell it environment , such as --environment-secret-file ; the deprecated pool spellings still work, as the --environment-secret-file row describes.
Runner CLI flags Most flags have a corresponding environment variable. When both are set, the flag takes precedence. Duration flags take minutes or seconds on the CLI, but the paired environment variable is always in milliseconds, indicated by the _MS suffix, and the Default column shows the flag’s unit: --exit-if-unused-min 10 is equivalent to SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000 , and a Helm value like SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" means 15 milliseconds, not the 15-minute default.
Flag Env var Default Description --api-url <url> none https://api.anthropic.com API base URL. Override only for testing. --base-dir <path> SELF_HOSTED_RUNNER_BASE_DIR /workspace ; none on Windows Directory for repository checkouts and per-session working directories. The runner needs write access to this path or its parent. The runner creates the directory at startup and exits with cannot create or write to base directory when it can’t create or write to it.
Before v2.1.225, the runner created the directory when the first session started, so an unusable path failed sessions rather than startup. On Windows, which isn’t a supported runner host, there is no default: the runner exits at startup unless you pass the flag or set the variable. Use the same value on every runner in an environment. See Keep the base directory and capacity identical across runners . --capacity <n> none 1 Maximum concurrent sessions this runner handles.
All sessions belong to the same locked owner . Use the same value on every runner in an environment; see Keep the base directory and capacity identical across runners . --client-label <label> SELF_HOSTED_RUNNER_CLIENT_LABEL the host’s hostname Label the runner sends when it registers. The runner also reports it as the client_label label of claude_code_self_hosted_runner_info . Requires Claude Code v2.1.248 or later. --configure-git SELF_HOSTED_RUNNER_CONFIGURE_GIT=1 off At startup, write global git identity, enable Anthropic commit signing, turn on git push negotiation, and install commit hooks that append a Co-authored-by: trailer.
Push negotiation requires Claude Code v2.1.257 or later. See Configure git . --confine-repo-settings <mode> SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS warn Sets the mode of the guard that flags a session when a repository’s committed settings try to grant write or read access outside that session’s own workspace, set environment variables, or override the operator’s sandbox or hooks posture, such as sandbox.enabled: false or disableAllHooks .
The default warn logs the violation and still starts the session, enforce refuses the session, and off disables the scan. See Harden your deployment . --debug-token-dir <path> SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR unset Write live tokens to disk for inspection. Debug only; don’t use in production. --defer-shutdown-max-min <n> SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS 0 On the first SIGTERM or SIGINT , keep serving the sessions already attached instead of draining them, then release whatever is still attached N minutes later and exit.
Raise your host’s stop timeout before you set this. See Defer the drain past the first signal . 0 disables. Requires Claude Code v2.1.238 or later. --drain-grace-sec <n> SELF_HOSTED_RUNNER_DRAIN_GRACE_MS 0 Until the runner receives a shutdown signal or reaches its retire time, controls when the runner exits after its active sessions finish: 0 exits immediately without polling for more, and a positive value keeps the runner alive and re-polling the locked owner’s queue for that many seconds first, at the cost of the per-session container isolation described in the hardening section .
After a first signal you deferred with --defer-shutdown-max-min , the runner exits as soon as it holds no sessions, whatever you set here. --drain-marker-file <path> SELF_HOSTED_RUNNER_DRAIN_MARKER_FILE unset Marker file that your host writes to announce a graceful drain before sending SIGTERM . When the file exists as the drain starts, the runner reports its exit to Anthropic as a host drain rather than a plain shutdown signal.
The drain itself, including the --drain-wait-sec hold, runs the same as without the flag. Name a path on a local filesystem that sessions can’t write to. Requires Claude Code v2.1.271 or later. --drain-wait-sec <n> SELF_HOSTED_RUNNER_DRAIN_WAIT_MS 0 Once the drain starts, which is on SIGTERM unless you set --defer-shutdown-max-min , wait up to N seconds for each session’s in-flight turn and background tasks to finish before terminating the child.
During this wait, the runner counts a background task that has just finished as still running until the follow-up turn that reads its result starts, for at most the SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS window. Raise your stop timeout too . --environment-secret-file <path> SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET required Path to a file containing the environment secret, or, for runners spawned by the orchestrator , the single-use work-order JWT.
SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET carries the secret value directly, not a file path. The older --pool-secret-file flag and SELF_HOSTED_RUNNER_POOL_SECRET variable still work and print a deprecation notice to stderr; preview-program runner builds older than 2.1.216 only recognize those older names. --exec-path <path> SELF_HOSTED_RUNNER_EXEC_PATH own binary Binary or wrapper script to spawn for each session. See Wrapper scripts . --exit-if-unused-min <n> SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS 0 Exit after N minutes of polling with no work ever assigned, for autoscaler scale-down.
0 disables. --git-host-rewrite <from>=<to> none unset Rewrite https://<from>/... source URLs to https://<to>/... before cloning, for split-horizon DNS. Repeatable; flag only. --git-ssh-rewrite <host> none unset Rewrite https://<host>/... source URLs to git@<host>:... before cloning, for SSH-only git hosts. Repeatable; flag only. --health-port <port> SELF_HOSTED_RUNNER_HEALTH_PORT 8080 Port for the /healthz and /metrics listener.
Set 0 to disable. --hold-idle-file <path> SELF_HOSTED_RUNNER_HOLD_IDLE_FILE unset File your host keeps changing to hold an idle session on the runner. See Keep an idle session while its processes run . Requires Claude Code v2.1.311 or later. --hooks-dir <path> SELF_HOSTED_RUNNER_HOOKS_DIR unset Directory of lifecycle hook scripts. See Lifecycle hooks . --host-config-snapshot <mode> SELF_HOSTED_RUNNER_HOST_CONFIG_SNAPSHOT disk Where the runner keeps the startup snapshot of the host config directory that it seeds each
The rest of this page is on the live site.