Cloud environment setup

Environments define the container 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 container instance.

All Managed Agents API requests require the managed-agents-2026-04-01 beta header. The SDK sets the beta header automatically.

Create an environment

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

The name must be unique within your organization and workspace.

Use the environment in a session

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

Configuration options

Packages

The packages field pre-installs packages into the container 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; the default is latest.

Supported package managers:

Field	Package manager	Example
`apt`	System packages (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Go modules	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`

Networking

The networking field controls the container's outbound network access. It does not impact the web_search or web_fetch tools' allowed domains.

Mode	Description
`unrestricted`	Full outbound network access, except for a general safety blocklist. This is the default.
`limited`	Restricts container network access to the `allowed_hosts` list. Further access is enabled via the `allow_package_managers` and `allow_mcp_servers` bool.

For production deployments, use limited networking with an explicit allowed_hosts list. Follow the principle of least privilege by granting only the minimum network access your agent requires, and regularly audit your allowed domains.

When using limited networking:

allowed_hosts specifies domains the container can reach. These must be HTTPS-prefixed.
allow_mcp_servers permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the allowed_hosts array. Defaults to false.
allow_package_managers permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the allowed_hosts array. Defaults to false.

Environment lifecycle

Environments persist until explicitly archived or deleted.
Multiple sessions can reference the same environment.
Each session gets its own container instance. Sessions do not share file system state.
Environments are not versioned. If you frequently update your environments, you may want to log these updates on your side, to map environment state with sessions.

Manage environments

Pre-installed runtimes

Cloud containers include common runtimes out of the box. See Container reference for the full list of pre-installed languages, databases, and utilities.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

# List environments
environments=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"