Cloud environment setup

Environments define the sandbox configuration where your agent runs. You create an environment once, then reference its ID each time you start a session. Multiple sessions can share the same environment, but each session gets its own isolated sandbox (a fresh Linux container).

This page covers type: cloud environments. To run sandboxes on your own infrastructure, see Self-hosted sandboxes.

Create an environment

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

Use a unique, descriptive name so you can tell environments apart. This example uses limited networking with package managers allowed, so the sandbox can reach the package registries and code hosts. To let it reach other hosts, add them to allowed_hosts.

Use the environment in a session

Pass the environment ID as a string when creating a session.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Configuration options

Packages

The packages field pre-installs packages into the sandbox before the agent starts. Packages are installed by their respective package managers and cached across sessions that share the same environment. When multiple package managers are specified, they run in alphabetical order (apt, cargo, gem, go, npm, pip). You can optionally pin specific versions. Unpinned packages install the latest version. If the environment uses limited networking, also set networking.allow_package_managers to true; otherwise the request is rejected with a 400 error.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: limited
    allow_package_managers: true

Supported package managers:

Networking

The networking field controls the sandbox's outbound network access. It does not affect the web_search or web_fetch tools, which run on Anthropic's servers; to restrict the sites those tools can reach, set allowed_domains or blocked_domains on the tool's entry in the agent toolset. See Restrict web search and web fetch domains.

The following example creates an environment with limited networking:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

With limited networking and no other fields set, no hosts are allowed. Files, memory stores, and GitHub repositories that you attach to the session stay available. When a request from the sandbox on port 80 or 443 is refused because its host is not allowed, the response is a 403 that names the blocked host.

When using limited networking:

• allowed_hosts specifies domains the sandbox can reach. Specify bare hostnames or wildcard patterns (such as *.example.com). Do not include a URL scheme, port, or path.
• allow_mcp_servers allows outbound access to MCP server endpoints configured on the agent, beyond those listed in the allowed_hosts array. Defaults to false. While it is false, session creation fails with a 400 error if the agent declares an MCP server whose host is not in allowed_hosts. The same applies to an agent it can delegate to. To fix it, add the host to allowed_hosts or set allow_mcp_servers to true.
• allow_package_managers allows outbound access to a set of public package registries and code hosts beyond those listed in the allowed_hosts array. See Package manager hosts for the list. Defaults to false. Set it to true whenever the environment specifies packages; otherwise the request is rejected with a 400 error, even if the registry hosts are listed in allowed_hosts.

Package manager hosts

When allow_package_managers is true, the sandbox can reach the following hosts in addition to those in allowed_hosts. Anthropic maintains this list and can change it.

Risks of unrestricted networking

With unrestricted networking, code in the sandbox can send requests to any host on the internet, except for hosts on a general safety blocklist. Before you choose this mode, consider what the agent can do with that access:

• The agent can change things on external sites, not only read them: The bash tool can send any request. The agent can post data, submit forms, call APIs, and run scripts that change data on external sites. Even a request that only fetches a URL can change data on some sites.
• Nothing pauses these requests by default: The agent toolset's default permission policy is always_allow, so bash commands run without approval.
• Anything in the sandbox can leave it: This includes files, tool outputs, and any credentials or secrets you put in the sandbox.
• Fetched content can steer the agent: Web pages, API responses, and other content the agent reads can contain instructions (prompt injection) that change what it does next.
• The agent acts on your behalf: Its actions can violate a site's terms of service, or create accounts and records there.
• Model behavior is not a security control: The agent can act on external sites in ways you did not ask for, including retrying in a different way after a site blocks a request. Use network settings and permission policies to limit what it can do.
• The safety blocklist is not an allowlist: It does not limit which other sites the agent reaches, or what the agent does on them.

To reduce these risks, use limited networking with an explicit list of hosts. The following networking value allows api.example.com, plus the package manager hosts for an agent that installs packages:

{
  "type": "limited",
  "allowed_hosts": ["api.example.com"],
  "allow_package_managers": true
}

An agent that only uses the web_search and web_fetch tools does not need unrestricted networking if you can list the sites it needs. Networking says when allowed_hosts applies to those tools. Where it does, list those sites in allowed_hosts. Listing them in web_search's allowed_domains too makes it search those sites. A host that you add to allowed_hosts is also open to the sandbox. To restrict the tools further, see Restrict web search and web fetch domains.

Use unrestricted only when the agent must reach sites you cannot list in advance. In that case, keep secrets and sensitive files out of the sandbox, and give the agent only the credentials the task needs. Consider setting the bash tool's permission policy to always_ask or auto, and watch the session's events.

Environment lifecycle

• Environments persist until explicitly archived or deleted.
• Each session gets its own sandbox instance, even when multiple sessions reference the same environment. Sessions do not share filesystem state.
• Environments are not versioned. If you update an environment frequently, keep your own record of the changes so you can tell which configuration each session used.

Manage environments

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

Pre-installed runtimes

Cloud sandboxes include common language runtimes, databases, and command-line tools out of the box. See Cloud sandbox reference for the full list.

Next steps