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"`
`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 can contain type and an optional setup_script:

{"type": "self_hosted", "setup_script": "./initialize-worker.sh"}

A self_hosted config supports only type and an optional setup_script.

Environment packages

packages maps package managers to arrays of package spec strings. Requests support apt, npm, and pip. Cloud Environment responses also contain several reserved fields; 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"]`
`cargo`	array of string	Reserved response field; package installation through this field is not currently supported	`[]`
`gem`	array of string	Reserved response field; package installation through this field is not currently supported	`[]`
`go`	array of string	Reserved response field; package installation through this field is not currently supported	`[]`

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",
    "setup_script": "set -euo pipefail\n[ -d /data/workspace/repo/.git ] || git clone https://github.com/me/repo /data/workspace/repo\ncd /data/workspace/repo && pnpm install --frozen-lockfile"
  }
}

​Environment object

​Environment config

​Environment packages

​Environment setup script

Environment object

Environment config

Environment packages

Environment setup script