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. Returns the Identity ID for an Identity-owned resource, or `null` otherwise. See Identity ownership.
`icon_url`	string \| null	Icon URL associated by Forward
`binding_info`	Binding info	Binding information, such as Template reference counts

Identity の帰属

アカウント（または Workspace）には複数の Identity を作成できます。各 Identity は、そのアカウント（または Workspace）と連携する製品のエンドユーザーを表します。 Environment はアカウント（または Workspace）または特定の Identity に帰属できます。帰属によって、リソースを参照・操作できる範囲が決まります。

帰属の指定

Caller	Owner	How to select
PAT	Account / Workspace	Omit `identity_id` (the default, unchanged behavior).
PAT	A specific Identity	Pass the query parameter `identity_id=<identity_id>`.
Admin SAT	Workspace	Resolved automatically; parameters cannot switch ownership.
Identity-bound SAT	The bound Identity	Resolved automatically; parameters cannot switch ownership.

identity_id は Identity に属するリソースを操作する場合のみ使用する任意のパラメーターです。PAT では明示的に指定でき、省略時は管理者スコープになります。SAT では Identity スコープのトークンを発行し、空値を含め、このパラメーターを明示的に指定しないでください。指定すると HTTP 400 が返されます。 PAT で指定する Identity は、その PAT が表すアカウントまたは Workspace に属し、有効である必要があります。存在しない、無効化済み、削除済み、または呼び出し元に属さない場合は 404 が返されます。

帰属の分離

アカウントまたは Workspace のスコープからは、Identity に属する Environment を参照できません。
Identity は、アカウント（または Workspace）自体や同じアカウント内の他の Identity に属する Environment を参照できません。
有効な Identity スコープ（有効な identity_id を指定した PAT または Identity SAT）では、別スコープのリソースに対する ID 指定の取得、更新、アーカイブ、削除はすべて 404 を返します。リソースが存在しない場合と、他の所有者に属する場合を区別しません。
identity_id を指定しない PAT と Admin SAT は従来どおり、Owner mismatch に対して 403 を返します。

対応するエンドポイント

Environment の作成、検索、一覧取得、取得、更新、アーカイブ、削除は identity_id クエリパラメーターに対応しています。

GET /api/v1/forward/resources/batch は、現時点では identity_id に対応していません。参照範囲のルールは従来どおりです。

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

​Identity の帰属

​帰属の指定

​帰属の分離

​対応するエンドポイント

​Environment config

​self_hosted config

​cloud config response shape

​Environment packages

​Environment setup script

​Environment metadata

​Binding info

​List pagination fields

Environment object

Identity の帰属

帰属の指定

帰属の分離

対応するエンドポイント

Environment config

`self_hosted` config

`cloud` config response shape

Environment packages

Environment setup script

Environment metadata

Binding info

List pagination fields