The OpenAI Agents API lets you start a durable cloud agent through one session-creation call, while OpenAI runs the agent harness in the cloud. Novita Sandbox does not replace the Agents API or its OpenAI-managed harness. It gives you an isolated, stateful runtime for the self-hosted execution path documented by OpenAI: your application connects the sandbox to the session, the agent runs commands and edits files inside that runtime, and your application owns the sandbox lifecycle. This split matters when you want an OpenAI-hosted agent workflow, but need a separate, reusable environment for code, files, browsers, computer use, and long-running work.
This guide explains the API’s main concepts, how the harness and environment divide responsibilities, how to connect a Novita Sandbox to the self-hosted path, and what to check before moving from a prototype to production. If you only need the product page, Novita Sandbox is the best starting point.
Agents API, Agents SDK, and Responses API
OpenAI’s agent runtime comparison separates three integration models:
| You want to | Use | What manages state |
|---|---|---|
| Run a long-running task through an OpenAI-managed Codex harness | Agents API | Saved session configuration, turns, and items |
| Keep the agent loop in your application | Agents SDK | Your application state, SDK sessions, or Responses conversations |
| Call models directly and orchestrate everything yourself | Responses API | Your application history or Responses conversations |
The Agents API is the highest-level option. OpenAI describes it as access to the Codex harness through an OpenAI-managed API. It handles sessions, orchestration, context compaction, and recovery. The Agents SDK runs inside your application and gives you more control over deployment, storage, approvals, and runtime integration. The Responses API is closest to the model layer. This division is useful because “Agent” can mean either a reusable model/tool configuration or a durable running agent; the API documentation uses those terms differently in each runtime.
What is an Agent Harness?
An agent harness is the cloud service around an agent turn. It sends instructions and context to the model, invokes tools, tracks progress, handles interruption and resumption, and organizes work into an inspectable stream. In the Agents API, that harness is the managed Codex harness.
The managed harness supports:
- Running commands and code when an environment is attached.
- Applying relevant skills and instructions.
- Connecting to external data through tools or MCP.
- Steering the agent while it works.
- Summarizing previous work to manage the context window.
- Breaking work into subtasks and delegating to subagents.
- Resuming a session where it left off.
That does not mean your application disappears. Your application still creates the session, submits input, receives events, handles approvals or function calls, and decides how to store IDs and artifacts. The harness reduces orchestration work; it does not remove product policy.
Why an agent still needs a Sandbox
Some agents answer questions or call remote APIs without touching a filesystem. Others need to create files, install dependencies, execute scripts, inspect a browser, control a desktop, or keep a multi-step task alive while the user is away. A sandbox gives those actions a replaceable execution environment instead of letting them touch your product server or local machine.
The Agents API treats the environment as optional. OpenAI’s architecture documentation supports three execution choices:
none— the harness has no shell or filesystem. Function tools return results to the harness.openai_hosted— OpenAI provisions and manages the sandbox.self_hosted— your application starts and connects the environment, so you can use your own compute, private network, or custom software.
This is where the boundary between the two systems is clearest. The Agents API and OpenAI can host the harness, but a self-hosted environment lets your team select the execution platform. That choice affects isolation, filesystem shape, networking, SDKs, pause/resume behavior, billing, and how much infrastructure you maintain.
Novita Sandbox in this architecture
Novita Sandbox is a managed execution environment for AI agents. The official overview describes isolated, stateful runtimes for running code, installing dependencies, accessing files, using browsers, and preserving state across sessions without infrastructure management. In a direct Novita-only agent stack, your application creates the sandbox, the model or agent framework chooses tool calls, the sandbox executes them, and your application keeps policy, approvals, and storage outside the runtime.
With the Agents API, the recommended accurate framing is complementary rather than native: OpenAI’s current self-hosted sandbox guides list Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI, and Vercel as documented providers. Novita Sandbox is not currently in that provider list. The practical path is therefore to use Novita as your application-managed execution environment and connect it to an Agents API session through OpenAI’s self-hosted environment contract. That preserves the useful separation—OpenAI runs the durable harness, Novita Sandbox provides the runtime—without claiming an official provider integration that the current docs do not support.
Novita Sandbox is built around five concepts:
| Concept | What it gives the agent |
|---|---|
| Sandbox | An isolated runtime with its own filesystem and process space |
| Template | A reproducible starting image, dependencies, configuration, and setup |
| Snapshot | A saved sandbox state that can be reused to avoid repeated setup |
| Secret | Team-scoped, encrypted values that avoid hardcoding credentials |
| Region | The location of the current US v1/v2 endpoints |
The runtime supports coding-agent, browser-agent, data-analysis, research, and RL-style workloads. The Novita Sandbox overview is the source for current regions and lifecycle behavior.
Lifecycle, persistence, and long-running work
Novita Sandbox has three lifecycle states: running, paused, and killed. A running sandbox can execute commands and serve connections. A paused sandbox preserves filesystem and in-memory state, including running processes and variables, while CPU and RAM billing stops. Network connections are interrupted until resume. A killed sandbox is terminated and cannot be restored.
Two timeout controls drive the transitions: a sandbox timeout counts down from creation, and an idle timeout fires when no client has been connected for the configured duration. On either event, you can choose to pause rather than kill, and optionally enable auto-resume. This is useful for a code-editing task that waits for review, a browser session that pauses between steps, or a data-analysis notebook that resumes later with dependencies and variables intact.
Snapshots are different from pause. Pausing retains the current sandbox state for that instance. A snapshot captures state as a reusable environment, so a new sandbox can start with installed dependencies, configuration, and files already present. In production, use templates for repeatable base images, snapshots for reusable working states, and secrets for credentials rather than baking them into a template or snapshot.
Connect Novita to the self-hosted path
OpenAI’s self-hosted sandbox guide defines the connection shape. Your application creates a session with environment.type: "self_hosted", receives the environment ID and remote URL, starts an executor inside your runtime, then reports the session as connected. The official executor command is:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"The session event stream reports agent.session.environment.pending, connected, or failed. You must leave the executor running while the agent works and coordinate shutdown before stopping compute.
The following sketch shows the Novita side of that flow using the official Novita SDK. It creates a sandbox, prepares authentication without putting a secret in source code, and gives you the place to start the OpenAI executor. The exact way you inject the executor key and wait for the event stream depends on your application and OpenAI SDK version.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Create the Agents API session with environment.type=self_hosted, "
"then start codex exec-server here."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_idBefore using this path in production, verify the current OpenAI SDK objects, environment key name, remote URL behavior, and lifecycle requirements against OpenAI’s self-hosted sandbox guide. Do not assume the session API will manage the sandbox for you; with self_hosted, that responsibility is explicitly yours.
For the simpler non-Agents-API workflow, Novita’s Codex agent guide shows how to run the Codex CLI directly on the codex template, stream its output, and kill the sandbox when done.
Security and credentials
Treat the harness, sandbox, and application server as separate trust domains.
- Keep OpenAI API keys, Novita API keys, Git tokens, and database credentials outside prompts and source files.
- Use Novita Sandbox Secrets for team-scoped sensitive values used inside the sandbox.
- Use OpenAI vaults for credentials that OpenAI’s guidance says belong outside the sandbox.
- Prefer secure sandbox access. Novita docs say secure access is enabled automatically for sandboxes created with SDK version 2.0.0 or later; older custom templates may need a rebuild.
- Set explicit network policy and only widen it when a task needs it.
- Review generated code and artifacts before they receive broader permissions or reach production systems.
These controls work together. A sandbox reduces the blast radius of generated code, but it does not authorize the agent, validate intent, or decide which artifacts can leave the runtime.
Costs and limits
OpenAI bills Agents API model usage at the selected model’s API rates and OpenAI tools at their standard rates. For an OpenAI-hosted environment, the container rate applies. For a self-hosted path, execution resources are your provider’s cost.
Novita Sandbox billing is per second for CPU and RAM while a sandbox is running. Pausing stops CPU and RAM charges. Paused data is retained as persistent storage; each account includes 60 GB of free persistent storage, with additional storage billed hourly. Each running sandbox includes 20 GB of ephemeral storage. Official Sandbox credits and prices change, so confirm the current values on the Novita Sandbox pricing page.
Novita’s quota limits also matter for parallel workloads. At the time of writing, free accounts default to 5 concurrent sandboxes and paid accounts to 100; maximum single-sandbox vCPU and memory differ by tier. Enterprise limits can be adjusted. Check the quota limits guide and Sandbox.get_quota() rather than relying on examples in marketing pages.
Where this architecture fits
A self-hosted Novita runtime is a good fit when:
- The agent must execute code, modify files, install dependencies, run tests, browse the web, or interact with a desktop.
- The application needs stateful sessions across human delay, retries, or multi-step reviews.
- You want isolated execution separate from your product server.
- Your workload benefits from templates, snapshots, pause/resume, or reproducible environments.
It is not the right fit when:
- The task only needs remote function calls and no filesystem or shell.
- You need an OpenAI-managed environment and do not want to own environment lifecycle.
- You require a provider listed in OpenAI’s current direct sandbox-provider guides.
- Your compliance model requires provider-managed isolation controls that Novita has not documented for your deployment.
The safest evaluation is a small proof of concept with your real repository, commands, network policy, secret handling, and failure paths. Then measure startup, pause/resume, task completion, and the total cost of a representative run.
FAQ
Does Novita Sandbox natively integrate with the OpenAI Agents API?
Not according to OpenAI’s current environment-provider guides. The accurate architecture is to use the Agents API’s self-hosted environment path, start Novita Sandbox as your application-managed runtime, and run the documented executor inside it. Verify the current guides before release because provider integrations can change.
Do I still need Novita if OpenAI offers a hosted sandbox?
It depends on your requirements. OpenAI’s hosted sandbox is the low-operation path. Novita Sandbox is useful when you want a separate runtime choice for custom images, templates, snapshots, browser or computer-use workflows, stateful pause/resume, or provider-level control over resources.
Can the agent keep processes and files across a pause?
Yes. Novita’s pause/resume documentation says filesystem and in-memory state, including running processes and variables, are preserved. Network connections are interrupted until the sandbox resumes.
Is this the same as the OpenAI Agents SDK?
No. The Agents SDK runs in your application and gives you more control over the agent loop. The Agents API uses OpenAI’s managed Codex harness. Novita Sandbox can host execution for either pattern, but the session and orchestration behavior differ.
Where should I start?
Try the OpenAI Agents API quickstart to understand harness sessions and events. Then create a Novita Sandbox and decide whether its runtime, lifecycle, security, and cost model match your production needs.
