One of the following:
class None { type }

Runs the agent without an execution environment.

type: :none

The type of the object. Always none.

class OpenAIHosted { type, capability_directories, container_size, 10 more }

An existing OpenAI-hosted environment or new inline/template-based hosted configuration.

type: :openai_hosted

The type of the object. Always openai_hosted.

capability_directories: Array[String]

Directories that contain capabilities exposed to the agent. Defaults to an empty list.

minItems0
maxItems16384
container_size: :small | :medium | :large

The hosted container size. Omission selects the medium tier.

One of the following:
:small
:medium
:large
desktop: Desktop{ enabled}

Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled.

enabled: bool

Whether to provision the desktop and its browser proxy.

env: Hash[Symbol, String]

Environment variables made available to the agent.

environment_id: String

An existing prewarmed environment. Cannot be combined with a template or inline configuration.

minLength9
maxLength256
environment_template_id: String

A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy.

minLength0
maxLength64

Files available before the agent starts. Defaults to an empty list.

minItems0
maxItems50
One of the following:
class FileID { file_id, path, type }

A file previously uploaded through the OpenAI Files API.

file_id: String

The ID of the uploaded file.

minLength1
maxLength256
path: String

The absolute destination path inside /workspace.

minLength1
maxLength4096
type: :file_id

The type of the object. Always file_id.

class Inline { data, path, type }

A file supplied directly as standard-base64 data.

data: String

The standard-base64-encoded file contents.

minLength0
maxLength6990508
path: String

The absolute destination path inside /workspace.

minLength1
maxLength4096
type: :inline

The type of the object. Always inline.

network: Network{ access, allowed_domains, blocked_domains}

Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled.

access: :enabled | :disabled | :restricted

The environment’s network access mode.

One of the following:
:enabled

Allows unrestricted network access.

:disabled

Disables network access.

:restricted

Applies the configured domain restrictions.

allowed_domains: Array[String]

Domains the environment may access when network access is restricted.

minItems0
maxItems16384
blocked_domains: Array[String]

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.

minItems0
maxItems100
packages: Packages{ npm, python, system_}

Packages to install in the environment. Defaults to empty package lists.

npm: Array[String]

npm packages to install globally. Defaults to an empty list.

minItems0
maxItems16384
python: Array[String]

Python packages to install. Defaults to an empty list.

minItems0
maxItems16384
system_: Array[String]

System packages to install. Defaults to an empty list.

minItems0
maxItems16384
plugins: Array[HostedPluginParam { description, name, source, type } ]

Plugins provided as inline ZIP archives. Defaults to an empty list.

minItems0
maxItems32
description: String

The plugin description declared in .codex-plugin/plugin.json.

minLength0
maxLength1048576
name: String

The plugin name declared in .codex-plugin/plugin.json.

minLength1
maxLength64
source: InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

data: String

Standard-base64 encoded ZIP archive bytes.

minLength1
maxLength70254592
media_type: :"application/zip"

The archive media type, always application/zip.

type: :base64

The type of the object. Always base64.

type: :inline

The type of the object. Always inline.

setup_commands: Array[SetupCommandParam { command, cwd } ]

Ordered, confidential setup commands. Command bodies are never returned.

minItems0
maxItems16
command: String

The shell command to execute.

minLength0
maxLength65536
cwd: String

The absolute working directory. Defaults to /workspace.

minLength0
maxLength4096
skills: Array[HostedSkillParam]

Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list.

minItems0
maxItems200
One of the following:
class SkillReference { skill_id, type, version }

References a skill uploaded through the Skills API.

skill_id: String

The ID of the skill created through /v1/skills.

minLength1
maxLength64
type: :skill_reference

The type of the object. Always skill_reference.

version: String

The skill version, a positive integer or latest; omission selects the default.

minLength0
maxLength1048576
class Inline { description, name, source, type }

Supplies a skill ZIP directly in the session request.

description: String

The skill description declared in SKILL.md.

minLength0
maxLength1048576
name: String

The skill name declared in SKILL.md.

minLength1
maxLength64
source: InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

data: String

Standard-base64 encoded ZIP archive bytes.

minLength1
maxLength70254592
media_type: :"application/zip"

The archive media type, always application/zip.

type: :base64

The type of the object. Always base64.

type: :inline

The type of the object. Always inline.

class SelfHosted { type, workspace_directory, capability_directories }

An application-hosted environment configured inline.

type: :self_hosted

The type of the object. Always self_hosted.

workspace_directory: String

Absolute project directory inside the self-hosted environment.

minLength0
maxLength1048576
capability_directories: Array[String]

Directories that contain capabilities exposed to the agent. Defaults to an empty list.

minItems0
maxItems16384