Local evaluation stacks

Orca Agent Engine has two source-based local stacks. Both use Docker Compose for infrastructure and run application processes on the host, but they exercise different execution paths. Use Node 22.21 or later, or Node 24.9 or later, pnpm 9, Docker Compose v2, OpenSSL, and curl. The self-hosted worker launcher also requires lsof. To run the published images without building from source, use ork local.

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

Self-hosted worker stack

make self-hosted-up starts Postgres and RustFS, builds the packages, migrates the databases, and starts the registry and an environment worker on your machine. It creates a target=self_hosted environment and connects the worker over the public registry tunnel. The worker launches a session-runner for sessions assigned to that environment. This stack uses Postgres for transcripts; it does not start Kafka, Pulsar, the harness server, or AI Gateway.

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

The E2E uses the mock provider and needs no model credential. The launcher writes the environment ID and one-time Env Key to services/dev/run/self-hosted.env with restricted permissions. Keep that file private. It seeds a Workspace API key for the test fixture but does not expose it as a client credential. Each rerun creates a new environment. For a clean local database, use make self-hosted-up FRESH=1, which removes this stack's Postgres and RustFS data.

To exercise a real provider, supply its credential to the worker and include its variable in ORCA_RUNNER_ENV_PASSTHROUGH; the worker forwards only allowlisted variables to the runner. See the engine's local stack guide for provider requirements.

Full local stack

make stack-up starts Postgres, RustFS, the broker required by the selected transcript backend, and the external AI Gateway image through Compose. The registry and harness server run on the host. The default transcript backend is Kafka; Postgres mode needs no broker for transcripts, but the local gateway configuration still uses Kafka for audit. The local sandbox runtime needs the srt binary.

npm install -g @anthropic-ai/sandbox-runtime
cp services/dev/.env.example services/dev/.env
printf '\nAI_GATEWAY_IMAGE=docker.io/streamnative/orca-ai-gateway:0.4.3\n' >> services/dev/.env
# Set ANTHROPIC_API_KEY in services/dev/.env for real Claude sessions.
make stack-up
make stack-status
pnpm e2e:wire
make stack-down

pnpm e2e:wire does not need a model key. pnpm e2e:agent runs a real model loop and needs the matching provider key. The AI Gateway image is pulled independently of the engine; the launcher checks its required MCP resolver and LLM authorization contracts before starting it. See the local stack guide for image overrides and logs.

What's next

• Connect to the registry - bootstrap a Workspace key and configure a client.
• Deploy on Kubernetes - install the chart against external services.