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 [email protected])
• 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.