--- title: "Create an agent environment template" method: POST path: "/agents/environments/templates" tags: ["Agents"] --- # Create an agent environment template `POST /agents/environments/templates` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/agents/environments/templates` - Auth: HTTP bearer Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ## Request body - CreateEnvironmentTemplateParams: Parameters for creating a reusable, project-scoped OpenAI-hosted environment template. - `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`. - `name` string, nullable: An optional human-readable display name for the template. ## Response `201` The created environment template. - EnvironmentTemplateResource: Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - `id` string, required: The ID of the reusable environment template. - `name` string, nullable, required: An optional human-readable display name for the template. - `object` 'agent.environment.template', required: The object type. Always `agent.environment.template`. - `created_at` integer, required: The Unix timestamp, in seconds, when the template was created. - `updated_at` integer, required: The Unix timestamp, in seconds, when the template was last updated. - `packages` EnvironmentPackagesResource, required: Packages installed in an OpenAI-hosted environment. - `python` string[], required: Python packages installed in the environment. - `system` string[], required: System packages installed in the environment. - `npm` string[], required: npm packages installed globally in the environment. - `network` NetworkPolicyResource, required: Network access for an OpenAI-hosted environment. - `access` 'enabled' | 'disabled' | 'restricted', required: The network access mode for an OpenAI-hosted environment. - `allowed_domains` string[], required: Domains the environment may access when network access is restricted. - `desktop` DesktopResource, required: The effective desktop configuration for an OpenAI-hosted environment. - `enabled` boolean, required: Whether the environment provisions a desktop and browser proxy. - `capability_directories` string[], required: Directories that expose capabilities to the agent. - `skills` HostedTemplateSkillResource[], required: Safe skill metadata, preserving unresolved version selectors. - union: Safe metadata for a skill configured by an environment template. - object: A skill resolved afresh from the Skills API whenever a session starts. - `type` 'skill_reference', required: The type of the object. Always `skill_reference`. - `skill_id` string, required: The referenced skill ID. - `version` string, nullable, required: The requested version selector, including `latest`. - object: Safe metadata for an inline skill archive. - `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`. - `plugins` HostedPluginResource[], required: Safe plugin metadata, excluding inline 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. - `files` HostedTemplateFileResource[], required: Safe file metadata, excluding contents and session-scoped file IDs. - union: Safe metadata for a file configured by an environment template. - object: A project-scoped Files API reference resolved separately for each session. - `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 file's absolute path inside the environment. - object: Metadata for confidential inline file contents. - `type` 'inline', required: The type of the object. Always `inline`. - `path` string, required: The file's absolute path inside the environment. - `size_bytes` integer, required: The decoded size of the inline file in bytes. ## Other responses - `400`: The request was invalid. - `401`: Authentication or project context was missing. - `403`: The API key lacks the required management permission. - `404`: The requested environment definition was not found. - `500`: An internal error occurred. - `503`: The service is temporarily unavailable. ## Changes - **2026-10-05** `7f654af7f94f`: 1 info - endpoint added [Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/agents/environments/templates/post.md) --- [API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)