Architecture

OpenAI runs the agent harness. Your application sends it work and receives results. Add an environment when the agent needs compute or files.

The pieces

• Harness: The OpenAI-hosted Codex instance that runs the model and tool loop and maintains the agent’s session.
• Environment: Where the agent runs commands, executes code, and works with files. An environment can be a remote sandbox, your laptop, a Docker container, or an AWS Lambda function.
• Application server: Your code that connects the agent to your product. It submits tasks, receives events, and handles function tools. When you provide the environment, your code also manages its lifecycle.

Start with the pieces your task needs. The harness can work without an environment, and your application can receive progress through streaming or webhooks.

Start without an environment

An agent that answers questions or uses tools to access external services may not need its own compute or files. Set environment.type to none. This fragment shows the environment setting. Session creation also needs an agent and initial input:

12345{
  "environment": {
    "type": "none"
  }
}

Your application sends input to a session. The harness calls the model, uses the configured tools, and returns results. OpenAI maintains the session for later work.

The harness can call remote MCP tools directly. For function tools, your code receives each call, runs the function, and returns its result.

Without an environment, the built-in Bash and apply-patch tools, workspace files, and executor MCPs are unavailable.

The optional virtual runtime shown here provides files and shell commands through your application’s function tools.

Add an OpenAI-hosted environment

When the agent needs to run scripts, edit files, or create artifacts, set environment.type to openai_hosted. OpenAI creates and manages a sandbox for the session.

You configure the packages, files, and network access the agent needs. The harness runs commands in the sandbox directly. Your application continues to send tasks, receive events, and handle any function tools.

The dashed arrow applies only when you manage the environment yourself, as described below.

See OpenAI-hosted environments for configuration options.

Connect your own environment

Use environment.type: "self_hosted" when the agent needs your infrastructure, private network, or custom software.

Your code starts the environment and connects an executor to the session. The executor runs the commands and tools that the harness requests. Your application manages the connection and lifecycle without forwarding each command.

You own provisioning, reconnection, shutdown, and any files you need to preserve. Your application server or a webhook handler can manage this work.

Before stopping compute, coordinate incoming work and confirm that no execution is pending.

See Connect a sandbox and Sandbox lifecycle for setup and shutdown requirements.

Receive progress and results

With any environment choice, you can use either or both of these:

• Streaming: Receive detailed events as the agent works, such as output to display in your product.
• Webhooks: Receive session state changes without keeping a stream open. Your handler can retrieve results, run function tools, or manage a self-hosted environment.

Function tools need a handler that receives calls and returns results. If that handler is unavailable, the agent can remain waiting for a result. Failures in your event or lifecycle handlers can also interrupt progress updates or environment management.

See Session events and Webhooks for integration details.