Cloud environments

Every cloud session runs inside an environment. The environment decides what the session's VM can reach on the network, which environment variables it starts with, which secrets the proxy can attach for it, and what gets installed before Claude starts working. If your cloud sessions keep failing on npm install or can't reach an internal API, the environment is where you fix it.

Cloud sessions are available on Pro, Max and Team plans, and to Enterprise users with premium seats or Chat + Claude Code seats. The same environments are used wherever you start a cloud session: the Desktop app, the Claude mobile app, claude.ai/code in a browser, claude --cloud in the terminal, routines and Claude Tag. Any of those surfaces can also send work to a self-hosted environment instead.

Note: Remote Control is different. It connects the web and mobile apps to a session running on your own machine, so it uses your machine's network and files, not a cloud environment.

The Default environment

When you first onboard you get an environment called Default. How it appears depends on where you start:

Default is deliberately bare. It uses Trusted network access (package registries and the other allowlisted domains), defines no environment variables and has no setup script. Sessions in it start with only the pre-installed tools.

Which environment a session uses

If Default is all you have, everything runs there. Once you have more than one:

• Desktop app, mobile app and claude.ai/code: sessions you start use whatever the environment selector shows. If you haven't picked one, an organisation default set by an Owner fills the gap. Threads inside a project use the environment from the project's settings.
• The CLI: Claude Code uses your /remote-env choice. Without one, it falls back to the Anthropic-hosted environment if your list has one, otherwise to the first environment that isn't a bridge environment (the entry Remote Control registers to represent your own machine).
• Self-hosted override: --environment <environment-id> with a ccpool_ ID overrides both the /remote-env choice and the fallback for that one invocation. It needs Claude Code v2.1.224 or later, and it rejects Anthropic-hosted env_ IDs, so use /remote-env for those.

Create your own environment when the default stops being enough: Claude needs a domain outside the allowlist, a variable set for every session, or a toolchain installed before it starts.

Create and edit environments

There is no settings page or direct URL for environments. You manage them from the environment selector:

1. At claude.ai/code (after web onboarding), click the cloud icon showing the current environment's name, in the row above the message box. In the Desktop app the same selector sits in the prompt box.
2. Choose Cloud to list your environments.
3. Choose Add cloud environment, or hover over an existing one and click the settings icon on the right.

The dialog has fields for the name, network access level, environment variables and setup script. On Pro and Max, editing an existing environment also shows a Network secrets section.

Environments you create belong to your account. Organisation-wide ones created by an Owner show up in the same selector.

Environment variables

Variables use .env syntax, one KEY=value per line:

APP_ENV=staging
FEATURE_FLAGS=checkout_v2,new_search
SENTRY_ENVIRONMENT=claude-cloud
GREETING="Hello # this hash is kept because the value is quoted"

The rules worth knowing:

• Plain values need no quotes. If you wrap a value in a matching pair of quotes, the quotes are stripped.
• In an unquoted value, # starts a comment and the rest of the line is dropped. Quote anything containing # or spanning several lines.
• Every command Claude runs sees these as ordinary environment variables, with one exception: OTEL_* variables are kept for Claude Code's own telemetry export and are not passed to commands.
• A cloud session sets CLAUDE_AUTOCOMPACT_PCT_OVERRIDE itself, and its value wins over yours, so adding that key here does nothing.
• Anyone who uses the environment can read the values. Do not put secrets here. On Pro and Max, use a network secret instead.

When changes take effect

In an Anthropic-hosted environment, a session reads the variables when it is created and again whenever Claude Code restarts inside its VM. That happens in two cases:

• The VM paused after a few minutes idle and your next message restored it.
• The paused VM was reclaimed, so reopening the session built a fresh one.

So an edit does not reach a running session straight away. You cannot pause a VM yourself. If you need the new value now, ask Claude to set it inline on the command (APP_ENV=production ./scripts/smoke.sh) or start a new session.

Network secrets

A network secret lets Claude call an authenticated API without the key ever entering the VM. You store the key on the environment and list the hosts it belongs to. Anthropic's agent proxy then adds the key to matching requests after they leave the VM.

Requirements:

• Plan: Pro or Max only. The section does not appear on Team or Enterprise yet.
• Role: an organisation admin role in your claude.ai organisation. On Pro and Max you hold it for your own organisation.
• Environment: an existing Anthropic-hosted environment. Self-hosted environments do not have network secrets.
• Reachability: the API must accept connections from the internet, since requests leave from Anthropic's network.
• Encryption: organisations using customer-managed encryption keys cannot save network secrets.

To add one, open the environment for editing, find Network secrets and choose Add secret. For a typical API key, keep the Bearer credential type and fill in:

• Name: a label, for example Stripe test mode.
• Allowed websites: the API hosts, such as api.stripe.com. A leading *. matches every subdomain.
• Custom headers: one row for the header carrying the key. It starts as Authorization with a Bearer prefix; paste the key as the value. For an API that expects something like X-Api-Key with a bare value, rename the header and clear the prefix.

Other APIs can use a different Credential type from the list. Click Connect to save; the secret is stored immediately, without the dialog's Save changes button, and you can never view the value again. Secrets cannot be edited, so to change hosts or value, delete it and add it again.

To test it, start a session and ask Claude to curl the API. The call should succeed while the key appears in no variable or file. If the list marks a secret Not sent, the note under it explains why. Watch for two secrets whose hosts overlap without matching exactly: neither gets a marker, but only one is sent.

A secret applies to every session in the environment, whoever started it, until you delete it. Hosts on a secret are reachable even if the network level would otherwise block them. The proxy never attaches a secret to:

• GitHub, which has its own proxy.
• The Anthropic API and the public registries api.anthropic.com, registry.npmjs.org, jsr.io, npm.jsr.io, pypi.org, files.pythonhosted.org, index.crates.io and proxy.golang.org.
• Requests from the setup script, because Claude Code only connects to the agent proxy after the script finishes.
• Claude Code's own telemetry export, which does not go through the agent proxy.

Pick a default from the CLI

/remote-env opens a picker of your environments and saves your choice to remote.defaultEnvironmentId in your user settings, so it applies to claude --cloud in every project. A higher-precedence layer, such as a repo's project settings, can still override it (see settings precedence). Self-hosted ccpool_... IDs are honoured from a stricter set of layers; the settings reference has the detail.

/remote-env only sets the default. It does not start a session and cannot create or edit environments.

Archive an environment

Open your environment for editing and choose Archive. Owners archive shared environments from the Cloud environments admin page. There is no delete. Archiving affects new work only:

• Running sessions carry on, and any network secrets stay attached to them. Delete secrets you no longer want before archiving.
• The environment disappears from the selector and /remote-env.
• Nothing new can start in it on any surface. If it was your CLI default, CLI sessions fall back as described above. Anything pinned to it explicitly, such as a routine, stops being able to start sessions until you repoint it.

Organisation-shared environments

On Team and Enterprise, an Owner can create environments shared with every member. Owners manage everything on the Cloud environments admin page, including self-hosted environments; the Admin role cannot open that page. The roles that can open it match those for server-managed settings.

Shared environments appear under an Organization heading in the selector, after each member's Personal ones. Clicking the settings icon on a shared one shows a read-only summary, even to Owners. An Owner can make one available in two ways:

• Create it shared on the Cloud environments page in admin settings, with a name, network level, variables and setup script. Editing and archiving happen there too.
• Share a personal one from the Who can use it row in its edit dialog. It keeps its ID, so sessions and routines already using it are unaffected.

The organisation's default environment is chosen separately at claude.ai/admin-settings/claude-code. Every member's sessions read a shared environment's variables, so keep secrets out of them.

Environments for Claude Tag channels

In Claude Tag channels, Claude acts as the organisation's shared identity, so channel sessions only use organisation-level environments: shared or self-hosted. If a channel needs a toolchain that isn't pre-installed (.NET is the classic case), an Owner creates a shared environment with a setup script that installs it, then either makes it the organisation default or pins it to the channel in the Claude Tag admin settings.

Network access

Each environment has one network access level controlling outbound connections from its sessions. Change it in the environment's edit dialog; for shared environments an Owner changes it on the admin page. Existing Anthropic-hosted sessions pick up a new level within about a minute, no restart needed.

Some traffic never touches the session's allowlist, so it works at every level:

• GitHub, through the GitHub proxy.
• MCP connectors you enable on a session or routine, because their traffic goes via Anthropic's servers. Turn off connectors you don't need.
• Hosts listed on the environment's network secrets (apart from the exclusions above).
• The Anthropic API for Claude Code's own requests, even at None.

A custom allowlist

Choose Custom, then put one domain per line in Allowed domains. For a project that talks to a staging API, a private package mirror and an internal service mesh, that might be:

staging-api.acme.dev
npm.mirror.acme.dev
*.svc.acme.dev

A leading *. matches any subdomain. Tick Also include default list of common package managers to keep the Trusted list as well; leave it unticked to allow only what you typed.

You do not need *.frame.claudeusercontent.com for sessions to read your organisation's artifacts, because Claude Code falls back to its Anthropic connection. Add it if sessions open other organisations' public artifacts, and keep it in allowlists for the local CLI or self-hosted runners (see network configuration).

There is no organisation-level allowlist that admins can push to everyone's environments, and no server-managed setting adds domains either. To standardise a list, an Owner creates a shared environment with Custom access.

GitHub proxy

In Anthropic-hosted environments, every GitHub operation goes through a dedicated proxy that keeps your real GitHub credentials outside the VM, whatever the network level. It behaves like this:

• Git: the git client in the VM holds a scoped credential that the proxy checks and swaps for your real token.
• API calls: built-in GitHub tools, and gh when it is using the proxy-injected placeholder, go out with your real credentials substituted.
• Pushes: branch deletions and pushes of anything other than a branch (tags, for example) are rejected. It does not restrict which branches can be pushed; use GitHub branch protection or rulesets for that.
• Scope: API requests only work for repositories attached to the session. Others get a 403 starting GitHub access to and containing is not enabled for this session.
• No GraphQL: GraphQL requests get a 403 starting GitHub GraphQL is not available from Claude Code sessions, pointing at the REST form gh api repos/{owner}/{repo}/.... That includes gh pr and gh issue, and it applies even if you supply your own GH_TOKEN. GraphQL-only features such as Projects v2 are out of reach.

Raw files from public repositories come from raw.githubusercontent.com, which goes through the security proxy and is on the Trusted list.

Self-hosted environments authenticate git with credentials your deployment provides, with an opt-in to this same proxy; see deploying self-hosted environments.

Security proxy

All outbound internet traffic from an Anthropic-hosted session passes through an HTTP/HTTPS proxy for abuse prevention and rate limiting. Self-hosted sessions leave through your own network boundary instead.

What's inside a cloud session

An Anthropic-hosted session gets a fresh VM running Ubuntu 24.04 on x86_64, regardless of your laptop's OS or CPU, with your repository cloned. If a dependency ships prebuilt binaries (native gems, Python wheels), the x86_64 Linux build is the one that matters.

What carries over from your machine

The rule of thumb: committed to the repo, it's there; only on your laptop, it isn't.

To keep personal preferences out of a shared repo, give one of your own (not a shared) environments a setup script that writes ~/.claude/CLAUDE.md:

#!/bin/bash
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
Write British English in comments and docs.
Run the linter before every commit.
EOF

Run /context in the next session and check that /root/.claude/CLAUDE.md is listed under Memory files. More on memory files in memory.

Installed tools

Bun is installed but has known problems fetching packages through the security proxy.

Ask Claude to run check-tools (a shell command on the VM, not a slash command) to list versions. For tools it skips, such as Ruby, PHP, bun, PostgreSQL or Redis, ask for the tool's own version command, for example redis-server --version.

Node lives in /opt/node20, /opt/node21 and /opt/node22, with 22 on PATH. To use 20, ask Claude to put /opt/node20/bin first on PATH. Anything not listed, such as the .NET SDK, needs a setup script, even if its registry is allowlisted.

GitHub issues and pull requests

Built-in GitHub tools let Claude read issues, list PRs, fetch diffs and comment without setup, authenticating through the GitHub proxy.

For gh and your own scripts you have two options:

• Set GH_TOKEN or GITHUB_TOKEN yourself as an environment variable. It reaches the VM unchanged, but anyone using the environment can read it.
• Leave both unset. When the proxy handles authentication, both read as the literal string proxy-injected and the proxy substitutes real credentials on the way out. gh api works for attached repositories, but a script that reads GITHUB_TOKEN directly only gets the placeholder.

Ask Claude to echo $GH_TOKEN to see which applies. gh is pre-installed and reads GH_TOKEN automatically. REST-based subcommands such as gh workflow list and gh api work; GraphQL-based ones like gh pr do not.

Linking work back to the session

A session can read its own ID from CLAUDE_CODE_REMOTE_SESSION_ID. Commits Claude makes in a cloud session carry a Claude-Session: <url> trailer, and PR bodies include the session URL on its own line. Set attribution.sessionUrl to false to turn both off.

For anything else, such as a release note or a Slack post, the value has a cse_ prefix but the URL needs session_. A quick conversion:

sid="${CLAUDE_CODE_REMOTE_SESSION_ID#cse_}"
printf 'Generated in https://claude.ai/code/session_%s\n' "$sid"

Tests, services and packages

You never get a shell on the VM; Claude runs everything, so put these in your prompt.

• Tests: "run the Go tests after each change" works out of the box for pre-installed runners. Runners your project declares, such as vitest, arrive with your dependencies.
• Services: PostgreSQL and Redis are installed but stopped. Claude starts them with service postgresql start and service redis-server start. Docker is available, so docker compose up works, with image pulls subject to the network level (Docker Hub and common registries are on the Trusted list). Pull or build large images in the setup script so the cache keeps them; containers still need starting each session.
• Packages: install anything extra in the setup script so it is cached. Mid-session installs work but don't carry over.

Resource limits

Approximate, and subject to change: 4 vCPUs, 16 GB RAM and 30 GB disk. Memory-hungry builds or tests may be killed. For bigger jobs, use Remote Control on your own hardware or a self-hosted environment.

Time limits

• Commands: the Bash tool defaults apply, 2 minutes per foreground command, extendable to 10. A command that hits its timeout moves to the background rather than being killed (unless it starts with sleep), and can run up to 30 more minutes. Setting BASH_DEFAULT_TIMEOUT_MS above 1800000 raises that background limit too. See the tools reference.
• SessionStart hooks: a command hook is cancelled after 600 seconds unless you set timeout (in seconds). Hooks with async: true are not timed out.
• Setup script: anything over roughly five minutes is not cached.
• Idle: a VM pauses after a few minutes without activity and may later be reclaimed.

To lengthen command timeouts for every session, add BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS (milliseconds) to the environment's variables, for example BASH_DEFAULT_TIMEOUT_MS=480000 for an eight-minute default. Both are listed in environment variables.

Setup scripts

A setup script is Bash that runs as root on Ubuntu 24.04 when a new session starts, before Claude Code launches. Use it for anything the VM needs that isn't pre-installed. Paste it into the Setup script field.

Here is one I use for a .NET and Terraform project, with independent installs run in parallel to stay inside the time budget:

#!/bin/bash
set -u

install_dotnet() {
  curl -fsSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh
  bash /tmp/dotnet-install.sh --channel 8.0 --install-dir /usr/local/dotnet
  ln -sf /usr/local/dotnet/dotnet /usr/local/bin/dotnet
}

install_terraform() {
  apt-get update && apt-get install -y unzip
  curl -fsSL https://releases.hashicorp.com/terraform/1.9.5/terraform_1.9.5_linux_amd64.zip -o /tmp/tf.zip
  unzip -o /tmp/tf.zip -d /usr/local/bin
}

install_dotnet &
install_terraform &
wait

docker compose -f /workspace/docker-compose.yml pull || true
exit 0

Rules the script must follow

• Exit zero. A non-zero exit means the session fails to start. Add || true to anything non-essential.
• Finish in about five minutes. Longer and the environment isn't cached. Parallelise with & and wait, and move any single slow download into a SessionStart hook that runs it in the background.
• Have network access. Installs need registries. Trusted covers npm, PyPI, RubyGems, crates.io and more; at None, installs fail.

Environment caching

The first session in an environment runs the script. If it finishes in time, Anthropic snapshots the filesystem and later sessions start from that snapshot, skipping the script. You don't manage this.

The snapshot holds files, not processes. Installed packages, pulled images and written files survive; a started database or a docker compose up stack does not, so start those per session.

The cache is rebuilt when you change the setup script or the allowed hosts, and when it expires after roughly seven days. Restoring an idle VM does not rerun the script, so a script change only reaches an existing session if its VM was reclaimed and rebuilt.

Setup scripts or SessionStart hooks?

User-level hooks in ~/.claude/settings.json don't reach the cloud. Anthropic-hosted sessions run hooks from the repository and from server-managed settings (except in Claude Tag sessions, which don't receive server-managed settings). Self-hosted sessions also run hooks seeded from the runner host's ~/.claude/ and from the runner image's managed settings file.

Cloud-only dependency installs with a hook

Pair a hook with a script that checks CLAUDE_CODE_REMOTE, which is true on the cloud VM and never true locally. In .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR\"/tools/cloud-bootstrap.sh" }
        ]
      }
    ]
  }
}

And tools/cloud-bootstrap.sh:

#!/bin/bash
[ "$CLAUDE_CODE_REMOTE" = "true" ] || exit 0

# Skip the install when the lockfile hasn't changed since last time
stamp=node_modules/.lock-hash
want=$(sha1sum pnpm-lock.yaml | cut -d' ' -f1)
if [ "$(cat "$stamp" 2>/dev/null)" != "$want" ]; then
  pnpm install --frozen-lockfile && echo "$want" > "$stamp"
fi
uv sync --quiet || true
exit 0

Caveats: multi-repo sessions don't load any repo's hooks, so use a setup script there; hooks need network access; some package managers (Bun) misbehave behind the security proxy; and hooks add latency on every start and resume because they aren't cached. Hooks are covered fully in hooks.

You can't replace the base image yet. Layer what you need on top with a setup script, or run your own image alongside Claude with docker compose.

Default allowed domains

With Trusted access, sessions can reach these hosts. An entry starting *. matches any subdomain.

Related

• Claude Code on the web
• Web quickstart
• Routines
• Self-hosted environments
• Hooks