Environment スキーマ

Environment object

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

フィールド	型	説明
`id`	string	Environment ID（`env_` プレフィックス付き）
`type`	string	固定値 `"environment"`
`name`	string	Environment name, up to 255 characters. It must not be empty after trimming leading and trailing whitespace
`description`	string	Environment の説明
`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.

フィールド	型	必須	説明
`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.

キー	型	説明	例
`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.

制約	値
型	string
最大長	64 KB
インタープリタ	`/bin/bash -lc`
実行タイミング	サンドボックス準備段階、`packages` インストール完了後
タイムアウト	10 分
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).

制約	値
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.

フィールド	型	説明
`agent_template_count`	integer	Number of Templates currently bound to the Environment

List pagination fields

フィールド	型	説明
`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