Copy

Environment object

Create, get, list, and update endpoints return this structure.

Field	Type	Description
`id`	string	Environment ID with the `env_` prefix
`type`	string	Always `"environment"`
`name`	string	Environment name, up to 255 characters. It must not be empty after trimming leading and trailing whitespace
`description`	string	Environment description
`config`	Environment config	Normalized Environment configuration. Missing package-manager fields are added
`metadata`	object	Environment metadata; defaults to `{}` when omitted
`archived_at`	string \| null	Archive time in RFC 3339 format; `null` while active
`created_at`	string	Creation time in RFC 3339 format
`updated_at`	string	Last update time in RFC 3339 format
`identity_id`	string \| null	Owning Forward identity; typically `null` when created with a PAT
`icon_url`	string \| null	Icon URL associated by Forward
`binding_info`	Binding info	Binding information, such as Template reference counts

Environment config

Environment runtime configuration. When omitted, it defaults to {"type":"cloud"}. When provided explicitly, it must not be null or an empty object.

Field	Type	Required	Description
`type`	string	Yes	`"cloud"` or `"self_hosted"`. Defaults to `cloud` only when the entire `config` object is omitted
`packages`	Environment packages	No	Preinstalled package declarations for a `cloud` Environment. Must not be `null`
`setup_script`	string	No	See Environment setup script

`self_hosted` config

A self_hosted Environment accepts only type and an optional setup_script. Supplying packages or another unsupported field returns 400 invalid_request_error.

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

`cloud` config response shape

A cloud config response includes every reserved package-manager array under packages; undeclared arrays are returned as []. For example:

{
  "type": "cloud",
  "packages": {
    "type": "packages",
    "apt": [],
    "cargo": [],
    "gem": [],
    "go": [],
    "npm": [],
    "pip": []
  }
}

Environment packages

packages maps package-manager names to arrays of package specification strings. apt, npm, and pip currently install packages. cargo, gem, and go are reserved response fields and cannot currently install dependencies here.

Key	Type	Description	Example
`type`	string	Always `"packages"` in responses; do not supply it in requests	`"packages"`
`apt`	array of string	Debian/Ubuntu package declarations, installed with `apt-get install -y`	`["git", "curl"]`
`npm`	array of string	Global Node.js package declarations, installed with `npm install -g`	`["pnpm@9"]`
`pip`	array of string	Python package declarations, installed with `pip install`	`["PyYAML==6.0.1"]`
`cargo`	array of string	Reserved response field; dependency installation through this field is not currently supported	`[]`
`gem`	array of string	Reserved response field; dependency installation through this field is not currently supported	`[]`
`go`	array of string	Reserved response field; dependency installation through this field is not currently supported	`[]`

Every value must be an array of strings. Undeclared package-manager arrays are returned as [].

Environment setup script

setup_script is a shell script run during sandbox preparation after packages installation. Use it for initialization that cannot be expressed with packages, such as cloning code, writing configuration files, or warming caches.

Constraint	Value
Type	string
Max length	64 KB
Interpreter	`/bin/bash -lc`
When it runs	Sandbox preparation, after `packages` installation
Timeout	10 minutes
Nonzero exit	Fails preparation of the current sandbox
Repeated execution	Does not run again after succeeding in the same sandbox; runs again after the sandbox is reclaimed and rebuilt

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

Environment metadata

Custom Environment metadata key-value pairs. created_by is reserved by Forward and must not be supplied by callers (supplying it returns 400).

Constraint	Value
Caller-supplied limit	Typically 15 custom key-value pairs
Maximum key length	64 characters
Value type	string
Maximum value length	512 characters

Binding info

Reference summary included by Forward in Environment responses.

Field	Type	Description
`agent_template_count`	integer	Number of Templates currently bound to the Environment

List pagination fields

Field	Type	Description
`data`	array of Environment objects	Records on the current page
`has_more`	boolean	Whether another page is available
`next_page`	string \| null	Forward cursor for the next page (recommended). Equals the current page's `last_id` when `has_more=true`; otherwise `null`
`first_id`	string \| null	ID of the first record on the current page
`last_id`	string \| null	ID of the last record on the current page

The request cursor parameters page, after_id, and before_id are mutually exclusive; providing more than one returns 400. Use page where possible; it has the same semantics as after_id.

​Environment object

​Environment config

​self_hosted config

​cloud config response shape

​Environment packages

​Environment setup script

​Environment metadata

​Binding info

​List pagination fields