# OpenAgentCore: The OpenAI Agents API, open source and self-hosted

> Source: <https://github.com/MiniMax-AI/OpenAgentCore>
> Published: 2026-11-22 21:18:43+00:00

**Key takeaway:** Setting OPENAI_BASE_URL to a self-hosted Core endpoint (https://core.example/v1) and OPENAI_API_KEY to a Project API key lets the unmodified official OpenAI SDK create agent sessions, with the harness selected via extra_body agent.x_agents_core.harness such as "codex".

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](https://openagentcore.dev/) · [Documentation](https://openagentcore.dev/docs/getting-started/) · [Quickstart](#quickstart) · [Contributing](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md)

**English** · [简体中文](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/README.zh-CN.md)

- **Same API as OpenAI.** Set`OPENAI_BASE_URL` and the[official OpenAI SDK](https://developers.openai.com/api/docs/libraries) , 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](https://openagentcore.dev/contracts/agents-api/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. Your own Linux, macOS or Windows machine also runs Sessions. See[Sandbox Provider protocol](https://openagentcore.dev/docs/sandbox-provider) .
- **Replaceable parts.** Sandbox Providers, workspace filesystems, Harnesses and model providers plug in through[defined protocols](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary) .

Install Core, Web and PostgreSQL on Linux or macOS with [Docker](https://openagentcore.dev/docs/getting-started/install#prerequisites):

```
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, E2B or OpenSandbox). [Install Core and Web](https://openagentcore.dev/docs/getting-started/install) 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:

``` python
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](https://openagentcore.dev/docs/getting-started/quickstart) waits for the result and reads it back.

Applications and operators use these Core APIs:

| API | Path | Used by | 
|---|---|---|
| **[Agents API](https://openagentcore.dev/docs/api/public-agent-api)** | `/v1` | Your applications. Same protocol as [OpenAI's Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) | 
| **[Core API](https://openagentcore.dev/contracts/agents-api/admin-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](https://openagentcore.dev/docs/architecture).

| I want to | Start with | 
|---|---|
| Install and operate an installation | [Install Core and Web](https://openagentcore.dev/docs/getting-started/install) , then[Operations](https://openagentcore.dev/docs/getting-started/operations) | 
| Build an application on the API | [Run your first Session](https://openagentcore.dev/docs/getting-started/quickstart) , then the[Agents API guide](https://openagentcore.dev/docs/api/public-agent-api) | 
| See a complete application | [Examples](https://openagentcore.dev/docs/examples) | 
| Run agents on my own machine | [Run self-hosted Sessions](https://openagentcore.dev/docs/getting-started/self-hosted) | 
| Check Harness capabilities and limits | [Harness capabilities](https://openagentcore.dev/contracts/agents-api/harness-capabilities) | 
| Understand the design | [Architecture](https://openagentcore.dev/docs/architecture) | 
| Add a sandbox, Harness or other component | [Develop OpenAgentCore](https://openagentcore.dev/docs/development) | 

Read [CONTRIBUTING.md](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md) before changing code. Report bugs and ask questions in [GitHub Issues](https://github.com/MiniMax-AI/OpenAgentCore/issues). Released under the [MIT License](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/LICENSE).
