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 beta:environments create \
 --name "python-dev" \
 --config '{type: cloud, networking: {type: unrestricted}}'

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.

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; the default is latest.

ant beta:environments create <<'YAML'
name: data-analysis
config:
 type: cloud
 packages:
 pip:
 - pandas
 - numpy
 - scikit-learn
 npm:
 - express
 networking:
 type: unrestricted
YAML

Supported package managers:

Networking

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

config = {
 "type": "cloud",
 "networking": {
 "type": "limited",
 "allowed_hosts": ["api.example.com"],
 "allow_mcp_servers": True,
 "allow_package_managers": True,
 },
}

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.
• 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 (such as PyPI and npm) 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 sandbox 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

# List environments
ant beta:environments list

# Retrieve a specific environment
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# Archive an environment (read-only, existing sessions continue)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# Delete an environment (only if no sessions reference it)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"

Pre-installed runtimes

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