Skip to main content
Cloud environments require Claude Code on the web, which is in research preview for Pro, Max, and Team users, and for Enterprise users with premium seats or Chat + Claude Code seats.
Each cloud session runs in a cloud environment. You can configure an environment to allow or deny network access, set environment variables for the session, and run a setup script before Claude starts working. The same environments apply wherever you start a cloud session: Claude Code on the web, the terminal with claude --cloud, Claude Tag, routines, the Claude mobile app, and the Desktop app. Claude Tag sessions can’t run in self-hosted environments yet; the other surfaces can route to any environment.
Remote Control sessions connect the web and mobile interfaces to a session on your own machine, which uses your machine’s network and files, not a cloud environment. Claude Tag channel sessions use shared environments only.

​
The Default environment

Onboarding sets up the Default environment for you, whether you connect through the web or a CLI flow such as /web-setup; if web onboarding shows an environment form instead of creating the environment, keep the form’s defaults to get the same Default environment. Default carries no configuration of its own: With only Default available, every session runs in it. When you have more than one environment, sessions choose one per surface:
  • On the web, the Desktop app, and the mobile app, sessions use the environment shown in the selector. An admin-set organization default fills the selection when you haven’t picked one.
  • From the CLI, sessions use your /remote-env pick, or fall back to your first available cloud environment. For a self-hosted environment, passing --environment <environment-id> with its ccpool_ ID when you dispatch a session overrides both for that invocation. The flag rejects Anthropic-hosted env_ IDs, so use /remote-env to target those. The flag requires Claude Code v2.1.224 or later.
Configure an environment when the default isn’t enough: when Claude needs to reach domains outside the default allowlist, needs environment variables set for its sessions, or needs dependencies installed before it starts working.

​
Configure your environment

Create, edit, and archive environments from the environment selector at claude.ai/code, which you reach after web onboarding. Environments you create are personal to your account; shared environments created by your admins appear in the same selector. See Installed tools for what’s available without any configuration.
1

Open the environment selector

On claude.ai/code, select the cloud icon showing the current environment’s name, in the row above the message box. There’s no settings page or direct URL for the selector.
The environment selector open above the message box at claude.ai/code. The cloud button showing the environment name Default sits in the row above the message box. The open menu lists a Local row with Download and Desktop only labels, a Cloud section where the Default environment is selected with a checkmark and shows a settings gear icon on hover, an Add cloud environment option, and a Remote Control section with setup instructions.
2

Add or edit an environment

Select Add cloud environment, or hover over an existing environment and select the settings icon that appears on the right. The dialog includes the name, network access level, environment variables, and setup script.
The New cloud environment dialog. A Name field with the placeholder Default, a Network access selector set to Trusted with links to the network policy and access levels, an Environment variables box showing .env-format placeholder text with a note that values are visible to anyone using the environment, a Setup script box described as a Bash script that runs when a new session starts before Claude Code launches, and Cancel and Create environment buttons.

​
Set environment variables

Environment variables use .env format, one KEY=value pair per line. Plain values don’t need quotes, and if you quote a value with a matching pair, the quotes don’t become part of the value. Quote a value that spans multiple lines or contains a #: in an unquoted value, # starts a comment and the rest of the line is dropped. The following example defines three variables.
Each session copies the environment’s values once, at startup, into ordinary environment variables that any command Claude runs can read. Because running sessions don’t re-read the configuration, editing or adding variables affects sessions you start afterward; sessions already running keep the values they started with. Claude Code on the web also sets some variables itself when it starts a session. For CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, the value Claude Code on the web sets overrides one you add here, so adding that key here has no effect. Anyone who uses the environment can read the values, and cloud environments have no dedicated secrets store, so don’t add API keys or other credentials. If a session needs a credential anyway, see What carries over from your setup.

​
Select an environment from the CLI

Run /remote-env in your terminal to choose the default environment for cloud sessions you create from the CLI, such as claude --cloud. The command opens a picker of your existing environments and saves your choice to the remote.defaultEnvironmentId key in your user settings, so it applies in every project on your machine until you change it, unless the same key is set at a higher-precedence settings layer, such as a repo’s project settings. A self-hosted environment ID, which has the form ccpool_..., follows a stricter source rule. See remote.defaultEnvironmentId for the settings layers Claude Code honors it from. /remote-env only sets the default: it doesn’t start a session, and it can’t add or edit environments. Manage them at claude.ai/code.

​
Archive an environment

To archive an environment, open it for editing and select Archive. You can’t delete an environment, only archive it. Archiving affects new sessions, not running ones:
  • Sessions already running in the environment continue to work.
  • The environment disappears from the selector and from /remote-env, so you can’t pick it for new sessions.
  • No new session can start in an archived environment, on any surface. If the environment was your saved CLI default, CLI cloud sessions fall back to your first available cloud environment. Anything configured with the environment explicitly, such as a routine, can’t start new sessions in it; point it at another environment.

​
Organization-shared environments

Owners and admins on Team and Enterprise plans can create cloud environments that are shared with every member of the organization; the same roles manage everything else on the Cloud environments admin page, including self-hosted environments. Shared environments appear in each member’s environment selector alongside their personal ones, so a team can standardize on one configuration instead of each member recreating it. Create, edit, and archive shared environments from the Cloud environments page in admin settings. Each shared environment has a name, a network access level, environment variables in .env format, and a setup script. Owners and admins choose the organization’s default environment separately, at claude.ai/admin-settings/claude-code. Values in a shared environment reach every member’s sessions in that environment. Like personal environments, shared environments have no dedicated secrets store, so don’t include secrets. In Claude Tag channels, Claude works as your organization’s shared identity, not as any member, so channel sessions use shared environments only. You can set the environment a channel uses in two ways:

​
Network access

Each environment sets one network access level, which controls the outbound connections its sessions can make. The default level, Trusted, allows package registries and other allowlisted domains; Custom takes your own domain list. To change an environment’s network access, open it for editing and use the Network access selector in the dialog. The cloud icon that opens the selector appears on the app surfaces listed under The Default environment and in the routine editor; personal environments don’t have a separate page in your claude.ai account settings.
MCP connectors you enable on a session or routine work without adding their hosts to Allowed domains, because connector traffic travels through Anthropic’s servers rather than the session’s network. You configure connectors per session or per routine; remove any you don’t need to limit which tools Claude can reach. This relies on the same Anthropic-bound channel noted under Security and isolation.

​
Access levels

The Network access field in the environment dialog takes one of four levels: GitHub operations use a separate proxy that is independent of this setting, and Claude Code’s connection to the Anthropic API still works at None, as noted under Security and isolation.

​
Allow specific domains

To allow domains that aren’t in the Trusted list, select Custom in the environment’s network access settings, then list one domain per line in the Allowed domains field. This example allows three hosts an internal project might need.
Sessions in this environment can now reach api.example.com, any subdomain of internal.example.com, and registry.example.com, and no other domains through the session’s network; GitHub traffic and MCP connector traffic don’t go through this allowlist. A leading *. matches every subdomain. To keep the Trusted domains too, check Also include default list of common package managers; leave it unchecked to allow only what you list. If sessions in the environment work with artifacts, include *.frame.claudeusercontent.com in your list. Claude Code fetches artifact content from that host. If you leave it out, Claude can’t read artifacts in sessions that run in the environment. Each environment has its own allowed-domains list; there’s no organization-level allowlist that admins can push to every member’s environments. Server-managed settings still apply inside cloud sessions, but none of them adds domains to the environment’s network allowlist.

​
GitHub proxy

In Anthropic-hosted environments, all GitHub operations go through a dedicated proxy that keeps your real GitHub credentials outside the session’s VM, independent of the environment’s access level. Sessions in a self-hosted environment authenticate git operations with credentials your deployment provides; Configure git covers the options, including per-session minted credentials and an opt-in to this same proxy. The proxy provides:
  • Git credentials: the git client inside the VM uses a scoped credential, which the proxy verifies and swaps for your actual GitHub token.
  • API requests: requests from the built-in GitHub tools, and from gh under the proxy-injected placeholder, go out with your real credentials substituted.
  • Push protection: git push works only against the session’s current working branch; cloning, fetching, and PR operations work normally.
  • Repository scope: GitHub API and release-asset requests reach only repositories attached to the session, so a setup script that downloads release assets from an unattached repository gets a 403.
  • GraphQL restrictions: the proxy serves only a pinned set of GraphQL operations for pull-request workflows. The proxy rejects everything else on the GraphQL endpoint with a 403 that says This GraphQL query is not enabled for this session and names the REST fallback, gh api repos/{owner}/{repo}/.... The restriction applies to every request through the proxy regardless of the credentials you supply, so a GH_TOKEN you set gets the same 403. Claude can’t reach GitHub APIs that exist only in GraphQL, such as Projects v2, through the proxy.
Committed files from public repositories arrive through raw.githubusercontent.com, which the security proxy handles instead. That domain is in the default Trusted list, so those files stay reachable unless the environment’s access level excludes it.

​
Security proxy

Cloud sessions in Anthropic-hosted environments run behind an HTTP/HTTPS network proxy for security and abuse prevention purposes; in a self-hosted environment, outbound traffic leaves through your own network boundary instead. All outbound internet traffic from an Anthropic-hosted session passes through this proxy, which provides:
  • Protection against malicious requests
  • Rate limiting and abuse prevention
  • Content filtering for enhanced security
  • A DNS-level audit trail of requested hostnames

​
What’s available in cloud sessions

In Anthropic-hosted environments, each session gets a fresh virtual machine (VM) running Ubuntu 24.04 on x86_64, regardless of your own operating system and CPU architecture, with your repository cloned and common toolchains pre-installed. When a dependency provides precompiled binaries, such as Ruby gems with native extensions or prebuilt Python wheels, use its x86_64 Linux build to match the VM. This section covers the Anthropic-hosted defaults, the built-in GitHub tools, how to run tests and services, and the resource limits each VM gets.
Sessions your organization routes to a self-hosted environment run on your own runners instead, with the tools your runner image provides.

​
What carries over from your setup

Cloud sessions start from a fresh clone of your repository. Anything you commit to the repo is available. Anything you’ve installed or configured only on your own machine isn’t available in the session. Your organization’s policy arrives separately through server-managed settings.