Orca Agent Engine

Orca Agent Engine is a self-hosted implementation of the managed-agents API: you define agents, run them in sessions, and stream each session's events. It follows Anthropic's Managed Agents beta (managed-agents-2026-04-01) closely enough that the official Anthropic SDKs can use it by changing their base URL. Agents, sessions, events, files, memory and credentials stay in infrastructure you operate.

It has four parts:

• A registry: the public, Anthropic-compatible REST and SSE API, and the control plane. It keeps its metadata in Postgres.
• A harness runtime that runs each session's agent loop: harness-server, or a session runner that dials the registry, including on machines you attach as self-hosted environments.
• Pluggable sandboxes where session code runs: local OS sandboxing, E2B, OpenSandbox, AgentENV, or an in-memory sandbox for tests.
• Egress through the AI gateway. MCP tool calls, and model calls when configured, leave through the AI gateway, which injects vault credentials so that they never enter the sandbox. The gateway is published as the image ghcr.io/orca-ae/orca-ai-gateway.

Session transcripts stream through Kafka (the default), Postgres or Pulsar. Files, memory and skills live in S3-compatible object storage.

_{The diagram shows the colocated model path, where the harness runs inside the sandbox and reaches the model through the AI gateway. In a cloud separate session the agent loop runs in harness-server, which calls the model provider directly unless the deployment (LLM_EGRESS_DEFAULT) or the session (metadata.orca_llm_egress) selects the gateway. MCP tool calls go through the gateway in both modes.}

Status

Orca Agent Engine is a developer preview. The current release line is 0.5.x. APIs, configuration and storage formats can change between minor releases. docs/compatibility.md lists the versions of the AI gateway, the ork CLI and the TypeScript SDK that were tested with this release.

Quick start

Neither path below needs a model API key.

You need:

• Docker with the Compose plugin
• Node.js 22 (22.21 or later) or Node.js 24.9 or later, and pnpm 9 (npm install -g pnpm@9.15.9)
• openssl, curl and lsof
• A C++ toolchain and Python 3, because pnpm install builds a native Pulsar binding: the Xcode Command Line Tools on macOS, or python3 make g++ binutils xz-utils on Debian and Ubuntu

git clone https://github.com/orca-ae/orca-agent-engine.git
cd orca-agent-engine
pnpm install --frozen-lockfile

Run a session on this machine

make self-hosted-up starts Postgres and RustFS in Docker, builds the workspace, and runs the registry on this machine. It then creates a self_hosted environment through the public API and attaches this machine to it with an environment worker. The e2e suite runs a session end to end with mock, a harness that answers without calling a model.

make self-hosted-up
pnpm e2e:self-hosted
make self-hosted-down

Run the full stack

make stack-up starts Postgres, Kafka, RustFS and the AI gateway in Docker, builds the workspace, runs the registry and harness-server on this machine, and waits until all three report healthy. The registry listens on http://localhost:8080. harness-server's default local sandbox needs srt, and on Linux also bubblewrap.

npm install -g @anthropic-ai/sandbox-runtime   # provides srt
make stack-up
make stack-status                              # health URLs, containers and process ids
pnpm e2e:wire                                  # the wire-protocol suite
make stack-down

To run real agents, copy services/dev/.env.example to services/dev/.env and set ANTHROPIC_API_KEY before make stack-up, then run pnpm e2e:agent. The model provider bills those calls. docs/managed-agents/local-stack.md covers the variables, the other suites, and troubleshooting.

Deploy on Kubernetes

The Helm chart in charts/ deploys the registry, harness-server and the AI gateway. It doesn't deploy Postgres, Kafka, Pulsar, object storage or OpenSandbox; you provide those. See docs/managed-agents/kubernetes.md.

API

Every route except the health probes requires a credential, including the discovery routes. Operations that Anthropic doesn't publish carry the orca-extension tag in openapi/managed-agents.yaml. The tag is computed by comparing against Anthropic's spec, which is vendored in this repository, so a client generator can leave those operations out. docs/managed-agents/conformance-matrix.md lists every difference from Anthropic's API, and docs/managed-agents/api-groups-and-extensions.md describes the URL model.

Configuration

Each layer is selected by configuration:

The harness catalog, packages/harness-catalog/src/catalog.ts, is the single source of truth for which harnesses exist and which modes each supports.

services/observability-exporter/ reads session transcripts from Kafka and delivers them as OTLP traces. The chart's exporter workload is off by default (observabilityExporter.enabled). auth-and-vaults.md describes how the registry authorizes it.

Repository layout

The services import the store libraries through workspace:* and call Kafka, Postgres and S3 in-process. There are no separate store services.

Documentation

• docs/managed-agents/README.md: the index of the design docs. Start with overview.md and architecture.md.
• docs/managed-agents/local-stack.md: the local stack, its variables and its troubleshooting.
• docs/managed-agents/kubernetes.md: deploying with Helm.
• docs/compatibility.md: the gateway, CLI and SDK versions tested with this release.
• docs/managed-agents/conformance.md: how differences from Anthropic's API are measured.
• docs/managed-agents/roadmap.md: what isn't built, and what would justify building it. Every other doc describes current behavior.
• proposals/: Orca Improvement Proposals, the design records behind changes others build on, and the process for proposing one.
• services/dev/README.md: Makefile targets and ports.
• packages/e2e-tests/README.md: the end-to-end suites.

Related components

These components aren't built from this repository. They're available as public images and packages under the Apache License 2.0:

Report problems with the AI gateway, the ork CLI or the TypeScript SDK in this repository's issues.

Community

• Questions: Discussions, Q&A
• Ideas: Discussions, Ideas
• Bugs and feature requests: Issues
• Contributing: CONTRIBUTING.md, and AI_POLICY.md if you use AI tools. Coding agents start with AGENTS.md.
• Security vulnerabilities: report them privately, as described in SECURITY.md.
• Conduct: CODE_OF_CONDUCT.md.
• Maintainers and decisions: MAINTAINERS.md and GOVERNANCE.md.

License

Orca Agent Engine is licensed under the Apache License 2.0. NOTICE lists third-party code copied into this repository, with its license and copyright notices.