> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novita.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://developers.openai.com/api/docs/guides/agents-api/overview).
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](https://platform.openai.com/agents?tab=environments) and save its API key as `OPENAI_ENVIRONMENT_KEY`.
* **Novita Sandbox** — install the [SDK or CLI](/guides/sandbox-installation), then set `NOVITA_API_KEY` in your environment.
### Create an Agent
Go to the [Agents page](https://platform.openai.com/agents) 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](https://platform.openai.com/agents?tab=sessions), 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](#run-the-executor). It looks like this:
```bash theme={"system"}
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote '' \
--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
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.
```bash CLI icon="terminal" theme={"system"}
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](/guides/sandbox-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](#connect-environment):
```bash theme={"system"}
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote '' \
--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:
```text theme={"system"}
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
Coming soon