Test self-hosted environments end to end

Self-hosted environments are in public beta on Team and Enterprise plans; Availability and limitations covers the enablement path. This page is the CI test recipe; see the quickstart for setup and Deploy to production for the fleet recipes.

In a self-hosted environment, Claude Code cloud sessions run on a runner image you build and maintain. Before rolling a new image to your production environment, drive a full session against a test environment from a script: create a session, read Claude’s reply, send a follow-up, and read that reply too. This is the shape of a CI smoke test that verifies your runner image, git access, and any custom tools before you promote a change. This recipe assumes you’ve already set up an environment and a runner, and that your CI job starts the runner process on the same host as the test script, the natural setup for testing a new runner image. A Stop hook you install on the runner writes each turn’s final reply to a local file, and the script reads it from there, so the only calls to the Anthropic API are the two dispatches themselves. If your test runners are on separate infrastructure, see Remote test runners.

Install the capture hook on your test runner

The read-back works through a Claude Code Stop hook: when Claude finishes a turn, the hook receives the final assistant message as last_assistant_message in its stdin JSON and appends it to $E2E_REPLY_DIR/<session_id>.txt. Install it the same way as the commit-nudge Stop hook, on the runner host’s ~/.claude/, which the runner seeds into every session.

Save the hook files

Save the two files below on the runner host:

The settings block: merge into ~/.claude/settings.json on the runner host
The script: save as ~/.claude/hooks/e2e-stop-hook-capture.sh on the runner host and make it executable

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/e2e-stop-hook-capture.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Stop hook for testing a self-hosted environment end to end: writes each
# turn's final assistant reply to $E2E_REPLY_DIR/<session_id>.txt so a
# co-located test driver can read it without calling the Anthropic API.
# Install on the TEST runner only. Requires jq.

# No-op unless the driver is listening. Never fail the turn.
[ -n "${E2E_REPLY_DIR:-}" ] && [ -d "$E2E_REPLY_DIR" ] || exit 0

# CLAUDE_CODE_REMOTE_SESSION_ID is exported in cse_... form; the session
# id the dispatch CLI prints is in session_... form. Same id, different
# prefix.
sid=$(printf '%s' "${CLAUDE_CODE_REMOTE_SESSION_ID:-}" | sed 's/^cse_/session_/')
[ -n "$sid" ] || exit 0

# last_assistant_message is absent when the final assistant turn had no
# text, such as a tool-use-only turn. The `// empty` filter makes that a
# zero-byte write rather than the literal string "null".
jq -r '.last_assistant_message // empty' >> "$E2E_REPLY_DIR/$sid.txt" 2>/dev/null
exit 0

Before you start the runner

Two things the hook depends on:

Install it before you start the runner. The runner snapshots ~/.claude/ once at startup, so a hook added to a running runner takes effect only after a restart.
Export E2E_REPLY_DIR to the runner process. The hook is a no-op when the variable is unset or the directory doesn’t exist, so set it wherever you start the runner, such as the systemd unit, pod spec, or CI step. The test script below requires it too.

Install this hook only on runners serving your test environment. It writes every session’s final reply to disk whenever E2E_REPLY_DIR exists, which is harmless on a throwaway CI runner but not something to carry into a production-environment runner image where the variable might be set by accident.

Run the test loop

The --environment and --ref dispatch flags require Claude Code v2.1.224 or later on the machine that runs the script, the same floor as the runner itself. With the hook in place and a runner started on this host, the test script:

Creates a session on the test environment with claude -p "<prompt>" --environment <environment-id> --output-format json, run from a git checkout so the CLI can auto-detect the repository from the origin remote. The optional --ref <branch> bases the session’s checkout on a named ref instead of local HEAD. The command creates the session, prints one line of JSON containing session_id, and exits without waiting for Claude’s reply.
Waits for the reply to appear in $E2E_REPLY_DIR/<session_id>.txt, written by the Stop hook on the runner once the turn completes.
Sends a follow-up with claude -p "<message>" --cloud <session_id> --output-format json (see Send a follow-up message to a running session), which posts a user event to the existing session and exits.
Waits for the follow-up’s reply the same way as step 2.

`--environment` dispatch behavior

In a non-interactive run, with -p or a piped prompt, Claude Code creates the session, prints the session ID and a link to it, and exits. From a terminal, claude --environment <id> "task" starts an attached interactive cloud session on the environment instead. The flag takes precedence over the remote.defaultEnvironmentId setting. It doesn’t support --output-format stream-json, and can’t be combined with flags that resume, attach to, or preconfigure a session, such as --resume, --continue, --teleport, --session-id, or --init-only. --cloud is rejected with a session ID or URL, and in non-interactive runs when it carries a description. A bare --cloud is treated as absent. From a terminal, you can pass the task as the --cloud description instead of a positional prompt.

Example script

The script below runs the full loop against $CLAUDE_TEST_ENVIRONMENT_ID, your test environment’s ccpool_... ID, shown in the environment’s detail dialog on the admin page or returned by the create-environment call, and asserts on a sentinel phrase in each reply. Run it from a git checkout of the repository you want the session to work in, after starting a runner on this host with the capture hook installed and E2E_REPLY_DIR exported.

#!/usr/bin/env bash
# End-to-end test against a self-hosted environment, using Stop-hook read-back.
# Prereqs: `claude auth login` has been run on this machine (see "Authenticate
# from CI" below); jq is installed; CLAUDE_TEST_ENVIRONMENT_ID names an
# environment whose runner is the one on this host, with the capture hook
# installed and E2E_REPLY_DIR in its environment.

set -euo pipefail

: "${CLAUDE_TEST_ENVIRONMENT_ID:=${CLAUDE_TEST_POOL_ID:-}}"  # CLAUDE_TEST_POOL_ID is the legacy spelling
: "${CLAUDE_TEST_ENVIRONMENT_ID:?set CLAUDE_TEST_ENVIRONMENT_ID to a ccpool_... id served by a runner on this host}"
: "${E2E_REPLY_DIR:?set E2E_REPLY_DIR to the directory the Stop hook on your test runner writes to, and export it to the runner process}"
: "${TEST_REPO_REF:=main}"

[ -d "$E2E_REPLY_DIR" ] || {
  echo "FAIL: E2E_REPLY_DIR ($E2E_REPLY_DIR) does not exist. The Stop hook on the runner needs it." >&2
  exit 1
}

# Waits until $E2E_REPLY_DIR/<session_id>.txt contains $2, or fails after
# 90 seconds. Tune the timeout to your environment's cold-start time. The
# file is written by the Stop hook on the runner.
await_reply() {
  local expect="$2" f="$E2E_REPLY_DIR/$1.txt"
  local deadline=$(($(date +%s) + 90))
  while :; do
    if [ -f "$f" ] && grep -qF -- "$expect" "$f"; then
      return
    fi
    [ "$(date +%s)" -lt "$deadline" ] || {
      echo "FAIL: '$expect' not in $f within 90s. The Stop hook on the runner did not write it." >&2
      echo "-- $E2E_REPLY_DIR contents --" >&2; ls -la "$E2E_REPLY_DIR" >&2
      [ -f "$f" ] && { echo "-- $f --" >&2; cat "$f" >&2; }
      exit 1
    }
    sleep 1
  done
}

# 1. Create the session on the test environment. Run from a git checkout
# so the CLI can auto-detect the repo. --ref pins the checkout to a named
# ref regardless of local HEAD.
TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"
EXPECT1="ok: custom tools are reachable"

Settings and permissions

Environments

Model and responses

Interface

Test self-hosted environments end to end

Install the capture hook on your test runner

Save the hook files

Before you start the runner

Run the test loop

`--environment` dispatch behavior

Example script

​Install the capture hook on your test runner

​Save the hook files

​Before you start the runner

​Run the test loop

​--environment dispatch behavior

​Example script

Install the capture hook on your test runner

Save the hook files

Before you start the runner

Run the test loop

`--environment` dispatch behavior

Example script