Environment schemas

Environment object

Returned by create, get, list, update, and archive endpoints.

Field	Type	Description
`id`	string	Environment ID with the `env_` prefix
`type`	string	Always `"environment"`
`name`	string	Environment name
`description`	string	Environment description
`config`	Environment config	Environment configuration
`metadata`	object	Metadata object. Defaults to `{}`
`archived_at`	string \| null	Archive time in UTC, or `null` when not archived
`created_at`	string	Creation time in UTC
`updated_at`	string	Last update time in UTC

Environment config

Field	Type	Required	Description
`type`	string	Yes	`"cloud"` or `"self_hosted"`
`networking`	Environment networking	No	Network access configuration
`packages`	Environment packages	No	Package declarations associated with the environment
`setup_script`	string	No	User setup script text. See Environment setup script

For self_hosted, the config must be exactly:

{"type": "self_hosted"}

Other config fields are only valid when type is "cloud".

Environment packages

packages maps package managers to arrays of package spec strings. Cloud environment responses include type plus apt, npm, and pip; omitted arrays are returned as [].

Key	Type	Description	Example
`type`	string	Always `"packages"` in responses	`"packages"`
`apt`	array of string	Debian/Ubuntu system package declarations	`["git", "curl", "build-essential"]`
`npm`	array of string	Node.js package declarations	`["typescript@5.0.0", "eslint"]`
`pip`	array of string	Python package declarations	`["pandas", "PyYAML==6.0.1"]`

Environment setup script

setup_script is a shell script executed during sandbox preparation, after packages are installed. It runs through /bin/bash -lc. Use it for initialization steps that cannot be expressed as packages, for example, cloning a repository, writing config files, or warming caches.

Constraint	Value
Type	string
Max length	64 KB
Interpreter	`/bin/bash -lc`
Timeout	10 minutes
When it runs	Sandbox preparation, after `packages` installation

On success a completion marker is written inside the sandbox so the script does not run twice in the same sandbox; when the sandbox is recreated, the script runs again. A non-zero exit aborts session startup. The error response includes the setup_script exit code and a stderr excerpt to help diagnose the failure.

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
  }
}

Environment networking

Field	Type	Required	Description
`type`	string	Yes	Valid values: `limited`, `unrestricted`
`allowed_hosts`	array of string	No	Host allowlist values returned with the config. Defaults to `[]`
`allow_package_managers`	boolean	No	Package manager access flag returned with the config. Defaults to `false`
`allow_mcp_servers`	boolean	No	MCP server access flag returned with the config. Defaults to `false`

Cloud environment setup

Choose the container, network, and dependencies your agent runs in.

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Best Practices

API reference

Environment schemas

Environment object

Environment config

Environment packages

Environment setup script

Environment networking

Cloud environment setup

​Environment object

​Environment config

​Environment packages

​Environment setup script

​Environment networking

​Related

Cloud environment setup

Environment object

Environment config

Environment packages

Environment setup script

Environment networking

Related