OpenAI Agents API

The Agents API gives your application access to the Codex harness through an OpenAI-managed API. OpenAI manages sessions, orchestration, context compaction, and recovery while your application provides tools and chooses its execution environment. Agents can operate in a sandbox where they can execute code, edit files, connect to MCP servers, and produce artifacts. For the full API surface, see the official Agents API documentation. This guide walks you through using Novita Sandbox as the execution environment for the OpenAI Agents API.

Application managed

Prerequisites

OpenAI Agent Environment — create one on the Environments tab and save its API key as OPENAI_ENVIRONMENT_KEY.
Novita Sandbox — install the SDK or CLI, then set NOVITA_API_KEY in your environment.

Create an Agent

Go to the Agents page and create a new Agent. This Agent is what your application will invoke through the Agents API. Give the Agent a name and description, then pick a model under Model. The values shown below are the ones used throughout this guide; the model and reasoning settings are yours to choose, but keep the Agent’s description focused on operating inside a sandbox.

Start a Session

On the Sessions tab, start a new Session. Select Self-hosted as the execution mode — this tells OpenAI to connect to an environment that you host and manage, which is where Novita Sandbox comes in. Choose the Agent you just created and set the workspace directory (defaults to /workspace). This directory must exist inside your sandbox.

Connect environment

Once the Session is created, open it and click Connect environment. The dialog walks you through connecting your self-hosted environment to the Session, starting with the code block you’ll run later. Save the Connect an environment command from that dialog — you will run it inside your sandbox in Run the Executor. It looks like this:

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
  codex exec-server \
    --remote '<remote_url>' \
    --environment-id '<environment_id>'

The --remote and --environment-id values are specific to this Session, so copy them from the dialog rather than from this page.

Launch the Sandbox

Only v2 regions are supported.

Next, start a sandbox from the openai-agents-api-executor template with the Novita CLI. This template provides the self-hosted environment your session connects to.

CLI

novita sandbox create openai-agents-api-executor --long-running --timeout 720h

By default a sandbox lives for at most one hour. --long-running lifts that cap so the sandbox can stay alive for the --timeout you set — here 720 hours (30 days), which lets the Session stay connected to the same environment without you having to recreate it.

A sandbox’s own filesystem is tied to that sandbox, so it disappears with it. If you want your code and data to survive beyond the sandbox — and be readable by other agents — manage your code with Git, and/or mount a volume to keep the data outside the sandbox and share it across sandboxes.

Run the Executor

Start the Codex executor inside the sandbox, pointing it at your Session. This is the Connect an environment command you saved from Connect environment:

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
  codex exec-server \
    --remote '<remote_url>' \
    --environment-id '<environment_id>'

--remote and --environment-id are specific to the Session you created — copy both values from its Connect environment dialog. CODEX_API_KEY is the API key of the OpenAI Agent Environment you created in the prerequisites.

Confirm the Connection

The Session is now wired up. In the Session page, send the agent a message asking it to report its runtime environment — for example:

Check the runtime environment on my machine.

The agent inspects the workspace and reports back. If the setup is correct, it describes the environment inside your sandbox rather than your local machine — in the example below, Debian GNU/Linux 12 (Bookworm) on kernel Linux 6.1.158, x86_64 — which confirms the Session is executing through the Novita Sandbox you launched.

Webhook managed

Novita Sandbox follows OpenAI’s best practices and provides a long-running controller, openai-agents-api-executor, which manages the relationship between Sessions and sandboxes for you. Compared with Application managed, there is no manual sandbox creation and no codex exec-server registration step — Sessions are connected to Novita-managed environments automatically as they run.

Prerequisites

Clone the executor repository

Clone the executor repository, which holds the webhook controller and client you deploy in the steps below:

git clone git@github.com:novitalabs/openai-agents-api-executor.git

Envs

Create a .env file from the repository’s .env.example, then fill in the variables below:

cp .env.example .env

Novita Sandbox — install the SDK or CLI, then set NOVITA_API_KEY in your environment.
OpenAI application key — create one on the API keys page, then set OPENAI_API_KEY to it. This key needs the api.agents.read, api.agents.write, and api.responses.write scopes; it stays in your application and never enters the sandbox.
OpenAI Agent Environment — create one on the Environments tab with every other permission set to None, and save its API key as OPENAI_EXECUTOR_API_KEY. This is the only key that enters the sandbox.
Agent ID — set OPENAI_AGENT_ID to the ID printed by --create-agent in Create the Agent. The controller serves only that Agent and ignores Sessions belonging to other Agents.
Webhook signing secret — set OPENAI_WEBHOOK_SECRET, which you get when you register the webhook. Leave it empty for the first deploy, then fill it in and redeploy.

Create the Agent

Create the Agent the controller will serve:

npm run webhook:client -- --create-agent <name>

It prints the new agent ID:

{"agent_id":"agent_1c0960ecfe5e41bb8d289525a2446c72d2d44445f38647ff92"}

Put that ID in .env as OPENAI_AGENT_ID. Pass --instructions and --model to give the Agent its own role; --update-agent <id> edits them in place, which keeps the agent ID and so needs no redeploy.

Get the Webhook URL

Deploy the controller, which receives OpenAI webhooks and starts or resumes a worker sandbox per Session:

npm run webhook:deploy

It prints the webhook URL exposed by the controller’s sandbox:

Reusing controller sandbox ir8oymt3mp5hu1qcfkjyl

Webhook: https://8000-ir8oymt3mp5hu1qcfkjyl.us-phx-1.sandbox.novita.ai/webhook
Controller log: /app/controller.log (inside ir8oymt3mp5hu1qcfkjyl)

Next: register that URL in the OpenAI platform under the project that owns
OPENAI_API_KEY, for these events:
  - agent.session.action_required
  - agent.session.failed
Then put the signing secret in OPENAI_WEBHOOK_SECRET and redeploy.

Until then the controller answers 503 "Webhook not configured".

The controller’s sandbox ID is saved to .controller.json. Rerunning webhook:deploy reconnects to the same controller and restarts it with fresh environment variables. If that sandbox is gone, a new one is created and the URL changes, so the webhook registered in the OpenAI platform has to be updated to match.

Register the Webhook

In the OpenAI platform, open Project settings → Webhooks and add a webhook pointing at the URL printed above. Subscribe it to these two events:

agent.session.action_required
agent.session.failed

Register it in the project that owns OPENAI_API_KEY — a webhook registered in another project of the same organization is never delivered.

Redeploy the Controller

Add the signing secret to .env as OPENAI_WEBHOOK_SECRET, then redeploy so the controller picks it up:

npm run webhook:deploy

Send Input

Send the Agent a message through the client, which talks to the Agent running in the worker sandbox:

npm run webhook:client -- --input "Check the runtime environment on my machine."

The agent inspects its workspace and reports the environment back. If the setup is correct, it describes the environment inside the sandbox — confirming the Session is executing through a Novita-managed worker, with no sandbox of your own to create or register.

The first line of output is the session ID; pass it back with --session-id to continue in the same workspace:

npm run webhook:client -- --session-id "$SESSION_ID" --input "Read it again."

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

Application managed

Prerequisites

Create an Agent

Start a Session

Connect environment

Launch the Sandbox

Run the Executor

Confirm the Connection

Webhook managed

Prerequisites

Clone the executor repository

Envs

Create the Agent

Get the Webhook URL

Register the Webhook

Redeploy the Controller

Send Input

​Application managed

​Prerequisites

​Create an Agent

​Start a Session

​Connect environment

​Launch the Sandbox

​Run the Executor

​Confirm the Connection

​Webhook managed

​Prerequisites

​Clone the executor repository

​Envs

​Create the Agent

​Get the Webhook URL

​Register the Webhook

​Redeploy the Controller

​Send Input

Application managed

Prerequisites

Create an Agent

Start a Session

Connect environment

Launch the Sandbox

Run the Executor

Confirm the Connection

Webhook managed

Prerequisites

Clone the executor repository

Envs

Create the Agent

Get the Webhook URL

Register the Webhook

Redeploy the Controller

Send Input