Create a managed runtime environment with a container, dependencies, network policy, initial files, and skills.
Endpoint
POST /agents/environments
Creates a managed runtime environment. A successful call returns 201, which means the environment is registered and asynchronous preparation has started. Creating a session that references the environment before preparation completes can fail.
Request bodyenvironmentobject (required)Environment configuration, see below
Properties type string (required)Environment type, fixed as openai_hostedenvironment_template_id string (optional)Environment template ID; the template must belong to the current workspace. Manage templates through Environment templates.env object (optional)Environment variables; names must match [A-Za-z_][A-Za-z0-9_]*, cannot be PATH, and cannot start with a reserved prefix; values cannot contain NULpackages object (optional)Packages grouped by npm, python, and systemnetwork object (optional)Network policy, see below
Properties access string (optional)Network access mode, enabled, disabled, or restrictedallowed_domains array<string> (optional)Allowed domains, required and non-empty when access=restricted; host names only, with no scheme, port, or wildcardarray (optional)Initial files; currently uses file_id to reference source files
Properties type string (required)File reference type, fixed as file_idpath string (required)Absolute path in the environment; must be under /workspace/file_id string (required)Source file ID returned by POST /agents/fileobject (optional)Desktop settings; only enabled=false is accepted, and enabled=true returns 400setup_commands array (optional)Setup commands executed in order. Each item requires command and accepts an optional cwd; cwd defaults to /workspaceskills array (optional)Skills; currently uses skill_reference, up to 32 items
Properties type string (required)Skill reference type, fixed as skill_referenceskill_id string (required)Skill resource IDversion string (optional)Skill version; if omitted, latest is resolved and frozen to a specific versionarray (optional)Capability discovery directories; must be under /workspace/array<string> / null (optional)Vaults to attach, up to 10A non-empty plugins array is rejected. desktop.enabled=true is rejected. skill_id comes from the Skill API. Create or list skills first: Create a Skill or List Skills.Create accepts an optional Idempotency-Key header. The same key and request body in the same workspace return the existing resource; the same key with a different body returns 409.When mounting an unrestricted credential, network.access must be restricted, and allowed_domains must be non-empty and valid.Example: "skills": [{"type": "skill_reference", "skill_id": "skill_xxx", "version": "1.0"}] | Request example |
Response fieldsidstringEnvironment IDobject stringEnvironment object type, fixed as agent.environmenttype stringEnvironment type, fixed as openai_hostedstatus stringEnvironment status: pending, ready, connected, disconnected, suspended, expired, or failedfiles arraySafe metadata for installed files; file content is not returned.
Properties id stringEnvironment file IDtype stringFile reference type, fixed as file_idpath stringFile path in the environmentsize_bytes integerFile size in bytesfile_id stringOriginal source file IDarraySafe metadata for installed skills; package content is not returned.
Properties type stringSkill reference type, fixed as skill_referencename stringSkill namedescription stringSkill descriptionskill_id stringSkill resource IDversion stringFrozen versionarrayPlugin list; currently [] for managed environments; plugin fields in historical records do not mean plugins can be createdA 201 does not mean the environment is ready. Retrieve the status and confirm ready before use. | Response example |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / missing_required_parameter, param=environment | Provide environment in the request body |
400 | invalid_request_error / invalid_request_error | Fix type and the configuration as described for environment |
404 | not_found_error / not_found_error | Use a template or environment that exists and is accessible in the current workspace |
409 | conflict_error / conflict_error | Use the same request body with the same idempotency key |
503 | server_error / environment_unavailable or template_storage_unavailable | Retry later. If it keeps failing, submit a ticket with x-request-id |
{"error":{"type","code","message","param"}}. Gateway errors can use a different structure. Keep the HTTP status, x-request-id, and a redacted request body for troubleshooting.