Deploy on Kubernetes
Install Orca Agent Engine with its Helm chart against external databases, object storage, a broker, and a sandbox service.
The Agent Engine v0.5.1 release chart installs the registry, harness server, AI Gateway, and an optional CLI toolset. It can also install an observability exporter. It does not install Postgres, Kafka, Pulsar, object storage, OpenSandbox, or an environment worker. To run target=self_hosted sessions, connect an environment worker separately through the registry's public tunnel. The local self-hosted worker stack exercises that path.
Prepare dependencies
| Dependency | Chart values or credentials |
|---|---|
| Postgres | Registry, file-store, and memory-store database URLs under external.databases or Kubernetes Secrets. A transcript-store database URL is also needed when transcriptStore.backend=postgres. |
| Transcript backend | transcriptStore.backend selects kafka (default), postgres, or pulsar. Configure the selected backend's connection settings. |
| Object storage | Configure objectStorage and its credentials. Sandbox mounts need a scoped STS role through objectStorage.stsRoleArn; static credentials are a development-only escape hatch. |
| Sandbox service | The default harness.sandboxRuntime=opensandbox needs an external OpenSandbox server and an allowed sandbox image. Other supported runtimes have their own settings. |
| AI Gateway audit | The in-chart gateway enables a required Kafka audit sink through aiGateway.audit.kafka, even when the transcript backend is Postgres or Pulsar. |
| Credentials | Supply the session JWT signing key, provider keys, database URLs, and storage credentials through Kubernetes Secrets. The chart's secretStore.mode=kubernetes stores registry vault credentials in a dedicated Secret. |
The gateway image is released independently of the Engine images. Pin images.aiGateway.repository and images.aiGateway.tag to a pullable build that supports the chart's dynamic MCP destination and vault resolvers. Configure imagePullSecrets if that registry requires authentication. The chart's default gateway tag is a development pin, not a compatibility guarantee for a newer Engine checkout. For a separately installed gateway, set aiGateway.enabled=false and configure its Service URL and ServiceAccount identity as described in the chart README. See Install the gateway for its own Helm chart.
The registry's internal listener uses projected Kubernetes ServiceAccount tokens and TokenReview by default. The Helm installer needs permission to create a ClusterRoleBinding to system:auth-delegator. Internal traffic is plain HTTP unless your cluster supplies mTLS or equivalent transport security. See the engine's Kubernetes deployment guide for SecretStore RBAC, TLS, and upgrade requirements.
Install
Create my-values.yaml with dependency endpoints and Secret references from the chart's v0.5.1 values file. The chart can use a chart-managed Secret, an existing database Secret, or per-service Secret references. Do not put plaintext production credentials in my-values.yaml. Add these public image pins to the same file; the gateway follows its own release line:
images:
registry:
repository: docker.io/streamnative/orca-registry-service-ts
tag: "0.5.1"
harness:
repository: docker.io/streamnative/orca-harness-server
tag: "0.5.1"
observabilityExporter:
repository: docker.io/streamnative/orca-observability-exporter
tag: "0.5.1"
aiGateway:
repository: docker.io/streamnative/orca-ai-gateway
tag: "0.4.3"
sandboxHarness:
claudeCode:
repository: docker.io/streamnative/sandbox-harness-claude-code
tag: "0.5.1"
digest: sha256:80cfee4761746bc167b5073e6d7236baddea6756cf31a00bbeb5b600e31cdd24
toolset:
enabled: falseThe packaged Engine chart points at GHCR images. This guide overrides Registry, Harness, exporter, Gateway, and sandbox harness with public Docker Hub releases. Its default toolset is the older CLI v0.2.0; this guide disables it and uses the public ork v0.5.0 install on the client host. Keep these image pins when you add external storage, broker, and credential values.
If you run the Claude Code harness in OpenSandbox with the Docker Hub mirror, configure its patched server with ORCA_TRUSTED_SANDBOX_REPOSITORY_PREFIXES='["docker.io/streamnative"]'. That setting authorizes the exact sandbox image repositories under the mirror prefix; see the engine's OpenSandbox trust policy.
Download the release chart and check the rendered manifests before installing:
curl -fsSLO https://github.com/orca-ae/orca-agent-engine/releases/download/v0.5.1/orca-managed-agents-0.5.1.tgz
helm template orca-managed-agents ./orca-managed-agents-0.5.1.tgz -f my-values.yaml
helm upgrade --install orca-managed-agents ./orca-managed-agents-0.5.1.tgz \
--namespace orca-managed-agents --create-namespace \
-f my-values.yamlBootstrap and connect
After the registry is ready, run the offline registry:bootstrap-admin command once with database access. It creates the first organization, Workspace, organization admin key, and platform key. Use the organization admin key on the admin listener to mint a Workspace API key; registry:create-admin-key is for rotating an admin key, not the initial Workspace-key step. Follow Workspace administration for the command inputs and key handling.
Expose only the registry's public listener to clients. Keep its internal and admin listeners private. Set the client URL to that listener's host root and follow Connect to the registry for the correct credential header. Anthropic SDKs can use the Claude Managed Agents beta header, but check the conformance matrix for partial operations.
The chart's regular Ingress routes the whole public listener. If you enable its Istio Gateway and AuthorizationPolicy instead, the default allowedPaths includes only /v1/*. Add /api, /apis, /apis/*, and /api/v1/* when clients need version and group discovery or the core alias. A worker connecting from outside the cluster also needs the public /v1/tunnels/* WebSocket path, covered by /v1/*.