README.md

The OpenAI Agents API, open source and self-hosted. Run Codex, Claude Code or MiniMax Code on your own machines with your own models, through the official OpenAI SDK.

Website · Documentation · Quickstart · Contributing

English · 简体中文

• Same API as OpenAI. Set OPENAI_BASE_URL and the official OpenAI SDK, or plain HTTP, works unchanged.
• Your agent, your model. Each Session runs Codex, Claude Code or MiniMax Code natively, as it runs on your machine, with the model provider you configure. See Harness capabilities.
• Compute that sleeps, workspaces that stay. On microsandbox, which keeps every workspace on independent storage, idle sandboxes release compute and resume on a compatible node with their files intact. E2B pauses idle sandboxes in place. Docker and your own Linux, macOS or Windows machine also run Sessions. See Sandbox Provider protocol.
• Replaceable parts. Sandbox Providers, workspace filesystems, Harnesses and model providers plug in through defined protocols.

Performance

The sandbox lifecycle on one microsandbox node, with E2B's create, pause and resume for comparison. Medians of 7 to 30 samples on 2026-10-25; each row links to its method and raw records, and scripts/benchmark.py reproduces them.

Operation	OpenAgentCore on microsandbox	E2B	Records
Create a sandbox	1.22 s	0.63 s	core, e2b
Sandbox created → initialization starts	0.98 s	—	core
Environment ready, preparation cache hit / miss	2.50 s / 7.35 s	—	sessions
Environment ready on a full node	5.90 s	—	sessions, core
Suspend an idle sandbox	3.33 s	1.04 s	core, e2b
Resume it; after dropping the node's page cache	1.75 s / 1.99 s	0.64 s	core, cold, e2b
First text of a Turn, suspended / running Session	3.51 s / 1.26 s	—	sessions

E2B times are SDK calls on the client, each with at least one 0.20 s API round trip; a resume makes two calls. OpenAgentCore's sandbox times are Core's own, over a 0.2 ms local network; Environment ready and first text are timed by an application on the Core host from its event stream, which Core sends in 100 ms steps. Setup lists the hosts and versions, and E2B how the two sides differ.

Limits

• Docker is a compatibility backend, for trusted workloads and hosts without KVM. Containers share the node's kernel, idle sandboxes never suspend, and files stay on the node's disk. See Choose a sandbox backend.
• One writer per workspace. A workspace is attached to one sandbox at a time, and storage keeps only its current files: no file history or forks. See Workspace filesystem protocol.
• Workspace storage needs Linux. The NFS adapter uses a kernel NFS mount on the Core host and on every node. See Set up workspace storage.
• Suspend is slower than E2B's pause: 3.33 s against 1.04 s. A Session that starts on a node already running its maximum number of sandboxes waits for an idle one to suspend, as Environment ready on a full node above shows. See Suspension.

Quickstart

Install Core, Web and PostgreSQL on Linux or macOS with Docker:

curl -fsSL https://openagentcore.dev/install.sh | bash

On Windows, in PowerShell:

irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex

In Web, sign in with the Core key the installer prints, configure the public address, set a default model, issue a Project API key and add sandbox capacity (a node or E2B). Install Core and Web covers each step.

Then call it with the OpenAI SDK, with OPENAI_BASE_URL set to your API base URL (https://core.example/v1) and OPENAI_API_KEY to the Project API key:

from openai import OpenAI

client = OpenAI()  # reads OPENAI_BASE_URL and OPENAI_API_KEY
session = client.beta.agents.sessions.create(
    environment={"type": "openai_hosted"},
    input="Create /workspace/hello.txt with a short greeting, then describe it.",
    extra_body={"agent": {"x_agents_core": {"harness": "codex"}}},
)
print(session.id)

Run your first Session waits for the result and reads it back.

How it works

Applications and operators use these Core APIs:

API	Path	Used by
Agents API	/v1	Your applications. Same protocol as OpenAI's Agents API
Core API	/core/v1	Operators, through Web

Core keeps durable execution state. The Runtime runs the chosen Harness inside the Environment. Each connection is a defined protocol, so any part can be replaced on its own. See Architecture.

Documentation

I want to	Start with
Install and operate an installation	Install Core and Web, then Operations
Build an application on the API	Run your first Session, then the Agents API guide
See a complete application	Examples
Run agents on my own machine	Run self-hosted Sessions
Check Harness capabilities and limits	Harness capabilities
Understand the design	Architecture
Add a sandbox, Harness or other component	Develop OpenAgentCore

Contributing and license

Read CONTRIBUTING.md before changing code. Report bugs and ask questions in GitHub Issues. Released under the MIT License.