Skip to main content
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:
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

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
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:
--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:
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

Coming soon
Last modified on September 11, 2026