orka

README

Orka

Kubernetes-native AI agent orchestration.

Getting Started · Architecture · API Reference · Documentation

---

Orka turns your Kubernetes cluster into an AI-powered task execution platform. Spin up swarms of AI agents that write code, review PRs, research topics, or run containers — each as an isolated Kubernetes Job with full scheduling, retries, and observability. A coordinator agent dynamically decomposes complex tasks, spawns specialist agents to work in parallel, and synthesizes their results — no manual orchestration graphs required.

One helm install, one LLM secret, and you're chatting with an orchestrator that handles the rest.

[!IMPORTANT] Orka is experimental and under active development. APIs, CRDs, and behavior may change without notice between releases, and it is not yet recommended for production use. Feedback, bug reports, and feature ideas are very welcome — please open an issue.

[!NOTE] The organization and repositories are intended to be donated to a community-governed foundation at the appropriate time. Until then, the project is governed by Microsoft policy, and external contributors are required to sign the Microsoft Contributor License Agreement (CLA).

Why Run AI Agents on Kubernetes?

No API keys on developer machines — LLM credentials live in Kubernetes Secrets, managed by your platform team. Developers connect via ServiceAccount tokens — no risk of leaked keys in dotfiles, shell history, or laptops.

Centralized control — One place to set model policies, rate limits, and allowed providers across every team. Swap models or providers without touching developer configs.

Every agent action is auditable — Tasks run as Kubernetes Jobs with full logs, Prometheus metrics, and result storage. Know exactly what every agent did, when, and at what cost.

Isolated execution — Each agent runs in its own Pod with a hardened security context: non-root, read-only rootfs, all capabilities dropped, seccomp enforced. Agents can't escape their sandbox.

Scale with your cluster — Priority scheduling, retry policies, concurrency limits, and cron-based execution — all handled by the Kubernetes control plane you already operate.

What Can You Build?

Parallel code review — Spawn a swarm of review agents — security, performance, test coverage, accessibility, whatever you need. Each reviews independently and in parallel, then the coordinator synthesizes findings into a single report.

Autonomous dev workflows — A coordinator agent dynamically breaks down a feature request, delegates implementation to specialist agents (backend, frontend, tests), and opens a PR with the combined result — no predefined workflow graphs.

Research with competing hypotheses — Multiple agents investigate different theories in parallel, challenge each other's findings, and converge on the strongest explanation. The adversarial structure avoids the anchoring bias of sequential investigation.

Scheduled operations — Cron-based agents that run daily security scans, dependency audits, or report generation — all with retry policies and webhook notifications.

Use your favorite AI client — Connect Continue, Cursor, or any OpenAI-compatible client to Orka's API. Your cluster manages the LLM credentials — developers just code.

CI/CD integration — Trigger agent tasks from GitHub Actions, monitor progress via the REST API, and gate deployments on agent analysis.

Features

• 🤖 AI Agents — Anthropic, OpenAI, or Azure OpenAI with tools, skills, and session persistence
• 🛠️ Agent Runtimes — Delegate repo-backed coding tasks to Codex CLI, Claude Code CLI, GitHub Copilot CLI, or OpenCode CLI
• 🔁 Autonomous Task Loops — Coordinators can iterate on long-running goals until complete, canceled, or at an iteration limit
• 🔀 Multi-Agent Coordination — Coordinators delegate to specialists with depth and concurrency controls
• 💬 Interactive Chat — Agentic orchestrator with SSE streaming that creates and manages agents and tasks for you
• 🌐 Generic Gateways — Versioned, authenticated ingress and idempotent outbound delivery for external messaging and event systems
• 🧠 Durable Memory — Namespace-scoped recall, transcript search, and reviewable memory proposals that can be applied
• 🛡️ Repository Security Scanning — Scheduled and incremental repository scans with threat models, validated findings, patch generation, and remediation PRs
• 🔎 Repository Monitors — Durable GitHub PR review queues with scheduled and webhook-triggered review runs
• 🧰 Agent Sandbox Workspaces — Experimental durable, reusable coding workspaces through agent-sandbox
• 🖥️ Web Dashboard — Built-in React UI embedded in the controller binary — zero extra deployments
• 📦 Declarative CRDs — Task, Agent, AgentRuntime, Tool, Provider, Skill, RepositoryScan, RepositoryMonitor, and SubstrateActorPool custom resources for GitOps workflows
• ⏰ Scheduled Tasks — Cron-based recurring execution with concurrency policies
• 🔌 REST & OpenAI-Compatible API — Full CRUD + /openai/v1/chat/completions endpoint for Continue, Cursor, and any OpenAI-compatible client
• 🔐 Kubernetes, OIDC & Transaction-Token Auth — ServiceAccount tokens by default, with optional OIDC and scoped vendor-neutral transaction governance
• 🔮 Anthropic-Compatible API — /anthropic/v1/messages endpoint for Claude Code and other Anthropic-native clients
• 📊 Observability — Prometheus metrics, structured logging, health probes, and optional OpenTelemetry traces + GenAI OTLP metrics
• 🔒 Hardened by Default — Non-root containers, read-only rootfs, ServiceAccount token auth

Quick Start

Install

helm install orka charts/orka \
  --namespace orka-system \
  --create-namespace

A fresh install creates all twelve cluster-scoped Orka CRDs. Use --skip-crds only when one designated platform or release owner already manages compatible Orka CRDs for the cluster.

[!IMPORTANT] Helm does not create or update files from crds/ during helm upgrade. Apply the CRDs from the exact target chart before every upgrade, including an upgrade from the previous chart that installed zero CRDs. Helm retains CRDs on uninstall. See the Helm CRD lifecycle guide.

For the promoted raw installer, pre-create the harness-wrapper authentication Secret before applying the manifest; the token is intentionally not committed:

set -euo pipefail

kubectl create namespace orka-system --dry-run=client -o yaml | kubectl apply -f -
if ! kubectl -n orka-system get secret harness-wrapper-auth >/dev/null 2>&1; then
  openssl rand -hex 32 | \
    kubectl -n orka-system create secret generic harness-wrapper-auth \
      --from-file=token=/dev/stdin
fi

kubectl apply -f deploy/orka.yaml

See config/harness-wrapper/README.md for the canonical installer prerequisite.

Set Up a Provider

kubectl create secret generic anthropic-secret \
  --from-literal=api-key=your-api-key

kubectl apply -f - <<EOF
apiVersion: core.orka.ai/v1alpha1
kind: Provider
metadata:
  name: anthropic
spec:
  type: anthropic
  secretRef:
    name: anthropic-secret
    key: api-key
  defaultModel: claude-sonnet-4-20250514
EOF

Start Chatting

Use the built-in dashboard, or connect any OpenAI-compatible client:

kubectl port-forward -n orka-system svc/orka-api 8080:8080

# Open the web dashboard
open http://localhost:8080

The built-in orchestrator creates agents, runs tasks, monitors progress, and returns results — all from natural language. See the OpenAI Compatibility and Anthropic Compatibility docs for proxy setup with your preferred client.

Documentation

Getting Started	Installation, quick start, CLI setup
Architecture	System design, components, and data flow
Configuration	CRD reference, Helm values, controller flags, metrics
Observability	OpenTelemetry traces, GenAI metrics, and task trace guidance
Agent Runtimes	Built-in CLI runtimes and bring-your-own remote AgentRuntime backends
CLI Harness Wrapper	Harness protocol wrapper for Codex, Claude, Copilot, and OpenCode CLI runtimes
Agent Sandbox	Experimental upstream agent-sandbox workspace execution for agent runtimes
Interactive Chat	Chat endpoint, tools, and SSE streaming
Multi-Agent Coordination	Coordinator agents and task delegation
Autonomous Tasks	Long-running coordinator loops with persisted plan state
Memory	Durable memory, proposals, transcript search, and validation
API Reference	REST API endpoints and usage examples
OpenAI Compatibility	OpenAI-compatible chat completions API
Anthropic Compatibility	Anthropic-compatible Messages API
Gateway API	Generic Gateway resources, ingress, delivery, and operator APIs
Operating Gateways	Gateway readiness, TLS, recovery, upgrades, and operations
Web Dashboard	Frontend architecture and pages
Security	Security model and hardening
Transaction Tokens	Configure strict transaction governance and TTS
Outbound Access Policies	Exchange resource credentials or route Tools through a trusted gateway
Repository Security Scanning	Repository scan workflow, threat models, findings, and remediation
Repository Monitors	Durable GitHub pull request monitor runs, review tasks, and dashboard state
GitHub Label Triggers	Trigger Orka agent tasks from GitHub labels such as agent:implement and agent:review
Development	Building, generated charts, releases, and contributing
Testing	Test structure, patterns, and commands