--- title: "Create an agent environment" method: POST path: "/agents/environments" tags: ["Agents"] --- # Create an agent environment `POST /agents/environments` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/agents/environments` - Auth: HTTP bearer Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta. ## Headers - `Idempotency-Key` string ## Request body - CreateAgentEnvironmentParams: Parameters for creating an execution environment before its sessions. - `environment` CreateEnvironmentParam, required: Provision an OpenAI-hosted environment from inline configuration or a template. - `type` 'openai_hosted', required: The type of the object. Always `openai_hosted`. - `packages` EnvironmentPackagesParam: Packages to install in an OpenAI-hosted environment. - `python` string[], nullable: Python packages to install. Defaults to an empty list. - `system` string[], nullable: System packages to install. Defaults to an empty list. - `npm` string[], nullable: npm packages to install globally. Defaults to an empty list. - `setup_commands` SetupCommandParam[], nullable: Ordered, confidential setup commands. Command bodies are never returned. - `command` string, required: The shell command to execute. - `cwd` string, nullable: The absolute working directory. Defaults to `/workspace`. - `network` NetworkPolicyParam: Network access for an OpenAI-hosted environment. - `access` 'enabled' | 'disabled' | 'restricted', required: The network access mode for an OpenAI-hosted environment. - `allowed_domains` string[], nullable: Domains the environment may access when network access is restricted. - `blocked_domains` string[], nullable: Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported. - `desktop` DesktopParam: Desktop configuration for an OpenAI-hosted environment. - `enabled` boolean, required: Whether to provision the desktop and its browser proxy. - `env` object, nullable: Environment variables made available to the agent. - `capability_directories` string[], nullable: Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `skills` HostedSkillParam[], nullable: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - union: A skill installed in an OpenAI-hosted environment. - object: References a skill uploaded through the Skills API. - `type` 'skill_reference', required: The type of the object. Always `skill_reference`. - `skill_id` string, required: The ID of the skill created through `/v1/skills`. - `version` string, nullable: The skill version, a positive integer or `latest`; omission selects the default. - object: Supplies a skill ZIP directly in the session request. - `type` 'inline', required: The type of the object. Always `inline`. - `name` string, required: The skill name declared in `SKILL.md`. - `description` string, required: The skill description declared in `SKILL.md`. - `source` InlineCapabilitySourceParam, required: Provides ZIP bytes encoded with standard base64. - `type` 'base64', required: The type of the object. Always `base64`. - `media_type` 'application/zip', required: The archive media type, always `application/zip`. - `data` string, required: Standard-base64 encoded ZIP archive bytes. - `plugins` HostedPluginParam[], nullable: Plugins provided as inline ZIP archives. Defaults to an empty list. - `type` 'inline', required: The type of the object. Always `inline`. - `name` string, required: The plugin name declared in `.codex-plugin/plugin.json`. - `description` string, required: The plugin description declared in `.codex-plugin/plugin.json`. - `source` InlineCapabilitySourceParam, required: Provides ZIP bytes encoded with standard base64. - `type` 'base64', required: The type of the object. Always `base64`. - `media_type` 'application/zip', required: The archive media type, always `application/zip`. - `data` string, required: Standard-base64 encoded ZIP archive bytes. - `files` HostedEnvironmentFileParam[], nullable: Files available before the agent starts. Defaults to an empty list. - union: A file materialized in an OpenAI-hosted execution environment. - object: A file previously uploaded through the OpenAI Files API. - `type` 'file_id', required: The type of the object. Always `file_id`. - `file_id` string, required: The ID of the uploaded file. - `path` string, required: The absolute destination path inside `/workspace`. - object: A file supplied directly as standard-base64 data. - `type` 'inline', required: The type of the object. Always `inline`. - `data` string, required: The standard-base64-encoded file contents. - `path` string, required: The absolute destination path inside `/workspace`. - `environment_template_id` string: A reusable hosted template applied before inline configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. - `vault_ids` string[], nullable: The IDs of up to 10 vaults made available to an OpenAI-hosted environment. ## Response `201` The created OpenAI-hosted environment. - PublicEnvironmentResource: Safe metadata for a first-class execution environment. - `type` 'openai_hosted' | 'self_hosted', required: The kind of execution environment. - `id` string, required: The ID of the environment. - `object` 'agent.environment', required: The object type. Always `agent.environment`. - `status` 'pending' | 'ready' | 'connected' | 'disconnected' | 'suspended' | 'expired' | 'failed', required: The public lifecycle status of an execution environment. - `files` HostedEnvironmentFileResource[], required: Files installed in the environment, without their contents. - union: Metadata for a file materialized in an OpenAI-hosted execution environment. - object: A file copied from the OpenAI Files API. - `type` 'file_id', required: The type of the object. Always `file_id`. - `id` string, required: The session-scoped ID of the file in the execution environment. - `file_id` string, required: The ID of the uploaded file. - `path` string, required: The file's absolute path inside the environment. - `size_bytes` integer, required: The decoded file size in bytes. - object: A file supplied inline when the session was created. - `type` 'inline', required: The type of the object. Always `inline`. - `id` string, required: The session-scoped ID of the file in the execution environment. - `path` string, required: The file's absolute path inside the environment. - `size_bytes` integer, required: The decoded file size in bytes. - `skills` HostedSkillResource[], required: Skills installed in the environment, without their archive contents. - union: A skill installed in an OpenAI-hosted environment. - object: A skill installed from the Skills API. - `type` 'skill_reference', required: The type of the object. Always `skill_reference`. - `skill_id` string, required: The referenced skill ID. - `version` string, required: The concrete skill version installed for this session. - `name` string, required: The installed skill name. - `description` string, required: The installed skill description. - object: A skill installed from an inline ZIP archive. - `type` 'inline', required: The type of the object. Always `inline`. - `name` string, required: The installed skill name. - `description` string, required: The installed skill description. - `plugins` HostedPluginResource[], required: Plugins installed in the environment, without their archive contents. - `type` 'inline', required: The type of the object. Always `inline`. - `name` string, required: The installed plugin name. - `description` string, required: The installed plugin description. ## Other responses - `400`: The request was invalid. - `401`: Authentication or project context was missing. - `403`: The API key lacks the required permission. - `404`: The requested environment or referenced resource was not found. - `409`: The request conflicted with the current environment state. - `429`: The request exceeded a rate or capacity limit. - `500`: An internal error occurred. - `503`: The service is temporarily unavailable. ## Changes - **2026-10-08** `c686bf249e4c`: 1 warning - added the new `suspended` enum value to the `status` response property for the response status `201` - **2026-10-08** `4ce25559b07f`: 1 info - endpoint added [Operation history](https://skmtc.dev/openai/apis/openapi/changes/agents/environments/post.md) --- [API](https://skmtc.dev/openai/apis/openapi.md) - [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/b7f3ab500153?raw)