Orka

Orka

[](https://github.com/gianlucamazza/orka/actions/workflows/ci.yml) [](LICENSE-MIT) [](LICENSE-APACHE) [](https://www.rust-lang.org)

A self-learning AI agent orchestration platform built in Rust.

Orka routes messages from Telegram, Discord, Slack, WhatsApp, and HTTP through a priority queue to LLM-powered agents. Agents execute tools, build knowledge via RAG, learn from experience, and coordinate through multi-agent graphs — extensible with WASM plugins and MCP/A2A protocols.

More demos

Real-time dashboard

Server status & skill listing

One-shot message

Demo assets are regenerated with just demo-check, just demo, or ./scripts/demo.sh build . The asset contract and environment setup live in [demo/README.md](demo/README.md).

Architecture

flowchart TD
    Clients["External ClientsTelegram · Discord · Slack · WhatsApp · HTTP"]
    Auth["Auth Middlewareorka-auth · API Key · JWT"]
    Adapters["AdaptersPlatform → Envelope conversion"]
    Bus["Message BusRedis Streams"]
    GW["GatewayDedup · Rate-limit · Session · Priority routing"]
    PQ["Priority QueueRedis Sorted SetUrgent > Normal > Background → DLQ"]
    Workers["Worker Pool (N concurrent)"]
    A2A["A2A Protocolorka-a2a · Agent card · JSON-RPC"]
    Eval["Eval Serviceorka-eval · Skill scenario testing"]

    subgraph Agent["Agent — GraphExecutor"]
        direction TB
        subgraph Context["  "]
            direction LR
            WS["WorkspaceSOUL.md · TOOLS.md"]
            GR["GuardrailsPre / Post"]
            Mem["MemoryKey-Val store"]
            Exp["ExperiencePrinciples + Reflection"]
        end
        Loop["Agentic LoopLLM call → stream → tool calls → repeat"]
        LLM["LLM RouterAnthropic · OpenAI · Ollama · Ollama CloudCircuit Breaker per provider"]
        Skills["Skill RegistryShell · Code · Web · HTTP · KnowledgeSchedule · MCP · Filesystem · System · WASM"]
        Loop --> LLM
        Loop --> Skills
    end

    Outbound["Outbound Bridgebus.publish('outbound')"]
    AdaptersOut["Adapters outboundRoute reply by channel_id"]
    Platforms["Telegram · Discord · Slack · WhatsApp · HTTP"]
    Ext["External integrationsQdrant · MCP servers · Web / HTTP APIs"]
    BG["Background servicesScheduler · Experience distillation · Observe (OTel / Prometheus)"]

    Clients --> Auth
    Auth --> Adapters
    Clients -.-> A2A
    Auth -.-> Eval
    Adapters -->|"publish('inbound')"| Bus
    Bus --> GW
    GW -->|"queue.push()"| PQ
    PQ -->|"queue.pop()"| Workers
    Workers --> Agent
    Skills --> Ext
    Agent --> Outbound
    Outbound --> AdaptersOut
    AdaptersOut --> Platforms
    Agent -.-> BG

For a detailed description of each subsystem and their interactions, see [docs/reference/architecture.md](docs/reference/architecture.md).

Features

• Multi-channel messaging — Telegram, Discord, Slack, WhatsApp, custom HTTP/WebSocket
• Priority queue — Redis Sorted Sets with Urgent / Normal / Background lanes
• LLM integration — Anthropic Claude, OpenAI, Ollama, and Ollama Cloud (OpenAI-compatible) with streaming support
• Skill system — Pluggable skills with schema validation and WASM plugin support
• MCP server — Model Context Protocol over JSON-RPC 2.0
• A2A protocol — Agent-to-Agent communication
• Agent router — Prefix-based routing with delegation
• Workspace config — Hot-reloadable agent configuration (SOUL.md, TOOLS.md)
• Knowledge base — RAG with Qdrant vector store and document ingestion
• Sandboxed execution — Process isolation and WASM sandboxing
• Guardrails — Input/output validation and content filtering
• Checkpointing — Per-node execution checkpoints with crash recovery and human-in-the-loop approval
• Multi-agent graphs — Fan-out/fan-in, state reducers, planning mode, rolling-window history
• Multi-modal — Vision support for image messages across LLM providers
• Circuit breaker — Resilience pattern for external services
• Observability — OpenTelemetry tracing, Prometheus metrics, Swagger UI, append-only JSONL audit log
• Security — JWT/API key auth, AES-256-GCM secret encryption, SSRF protection
• Scheduler — Cron-based recurring tasks
• Self-learning — Trajectory recording, principle reflection, and offline distillation
• Soft skills — Instruction-based SKILL.md skills injected into the agent system prompt
• MCP HTTP transport — Streamable HTTP (MCP spec 2025-03-26) with OAuth 2.1 Client Credentials
• Skill evaluation — TOML-based scenario runner for offline skill testing (orka-eval)
• WASM Component Model — Plugin SDK based on the WIT interface definition language
• CLI — Full-featured management tool with real-time TUI dashboard

Quick Start

Prerequisites

• Rust 1.91+
• Redis 7+
• Docker (optional)

With Docker Compose

Copy .env.example to .env and fill in any required values, then:

docker compose up

Manual Setup

# Start Redis (or Valkey — a fully compatible drop-in replacement)
docker run -d -p 6379:6379 redis:7-alpine

# Build and run
cargo build --release
./target/release/orka-server

Native Installation (Linux with systemd)

# Dev setup — installs common deps, starts Redis/Valkey, runs cargo check
just setup

# Production install — builds release binary, installs systemd service
just install
systemctl enable --now orka-server

# Uninstall (preserves config and data)
just uninstall

just setup supports common pacman, apt, and dnf based development environments. Native Arch packaging is also available via PKGBUILD.

The server starts two endpoints:

• http://localhost:8080 — Health endpoint
• http://localhost:8081 — Custom HTTP/WebSocket adapter

Send a message

curl -X POST http://localhost:8081/api/v1/message \
  -H "Content-Type: application/json" \
  -d '{"channel": "custom", "text": "Hello, Orka!"}'

Configuration

Orka reads configuration from orka.toml and ORKA_* environment variables. The repository root orka.toml is the canonical sample config kept in sync with the current parser.

For a complete reference of all configuration options, see the [Configuration Guide](docs/reference/configuration.md).

Environment Variables

| Variable | Description | | ---------------------------- | ------------------------------------------------------- | | ORKA_CONFIG | Path to config file (default: ./orka.toml) | | ORKA_ENV_FILE | Path to .env file for hot-reload | | ORKA_ENV / APP_ENV | production requires encryption key for secrets | | ORKA_SECRET_ENCRYPTION_KEY | 32-byte hex key for AES-256-GCM secret encryption | | ORKA_HOST_HOSTNAME | Override hostname in system info | | ORKA_SERVER_URL | CLI: server endpoint (default http://127.0.0.1:8080) | | ORKA_ADAPTER_URL | CLI: adapter endpoint (default http://127.0.0.1:8081) | | ORKA_API_KEY | CLI: API key for authenticated requests | | ANTHROPIC_API_KEY | Anthropic provider fallback | | MOONSHOT_API_KEY | Moonshot provider fallback | | OPENAI_API_KEY | OpenAI provider fallback | | TAVILY_API_KEY | Tavily web search key | | BRAVE_API_KEY | Brave web search key | | RUST_LOG | Overrides logging.level via tracing EnvFilter | | ORKA_GIT_SHA | Git SHA embedded at build time | | ORKA_BUILD_DATE | Build date embedded at build time | | ORKA_NO_UPDATE_CHECK | Disable automatic update check on CLI startup |

Config fields can also be overridden via ORKA____ (e.g., ORKA__REDIS__URL).

API Endpoints

Server (:8080):

| Method | Path | Description | | -------- | ------------------------------- | ---------------------------------------------------- | | GET | /health | Health check | | GET | /health/live | Liveness probe | | GET | /health/ready | Readiness probe | | GET | /metrics | Prometheus metrics (when observe.backend = "otlp" or prometheus) | | GET | /docs | Swagger UI (OpenAPI) | | GET | /api/v1/version | Version info | | GET | /api/v1/info | Server info and feature flags | | GET | /api/v1/dlq | List dead-letter entries | | DELETE | /api/v1/dlq | Purge dead-letter queue | | POST | /api/v1/dlq/{id}/replay | Replay a dead-letter entry | | GET | /api/v1/skills | List registered skills | | GET | /api/v1/soft-skills | List discovered soft skills | | GET | /api/v1/skills/{name} | Skill detail with schema | | POST | /api/v1/eval | Run eval scenarios | | GET | /api/v1/schedules | List scheduled tasks | | POST | /api/v1/schedules | Create a schedule | | DELETE | /api/v1/schedules/{id} | Delete a schedule | | GET | /api/v1/workspaces | List server workspaces | | GET | /api/v1/workspaces/{name} | Workspace detail | | GET | /api/v1/graph | Agent graph topology | | GET | /api/v1/experience/status | Experience system status | | GET | /api/v1/experience/principles | Retrieve learned principles | | POST | /api/v1/experience/distill | Trigger principle distillation | | GET | /api/v1/sessions | List active sessions | | GET | /api/v1/sessions/{id} | Session detail | | DELETE | /api/v1/sessions/{id} | Delete a session | | GET | /api/v1/runs/{run_id}/checkpoints | List checkpoint IDs for a run | | GET | /api/v1/runs/{run_id}/checkpoints/latest | Most recent checkpoint | | GET | /api/v1/runs/{run_id}/status | Run status from latest checkpoint | | POST | /api/v1/runs/{run_id}/approve | Approve an interrupted run (HITL) | | POST | /api/v1/runs/{run_id}/reject | Reject an interrupted run (HITL) |

Adapter (:8081):

| Method | Path | Description | | ------ | ----------------- | -------------------- | | POST | /api/v1/message | Send a message | | GET | /api/v1/ws | WebSocket connection | | GET | /api/v1/health | Adapter health |

> Hot-reload: Orka watches the .env file for changes. API key updates trigger automatic LLM client refresh without restart.

Workspaces

Agent behavior is configured through workspace files:

• SOUL.md — Agent personality and system prompt (markdown with YAML frontmatter)
• TOOLS.md — Tool usage guidelines for the LLM (plain markdown)

Runtime parameters (model, tokens, etc.) live in orka.toml under [[agents]] and [tools].

Orka currently uses a two-tier workspace model:

• Local repository workspace — the root SOUL.md and TOOLS.md discovered from the current working tree by local tooling and CLI flows.
• Built-in runtime workspaces — distributable workspace files under workspaces/, used by runtime registration and installation.

These are related but not interchangeable concepts. The root files define the local repo's active workspace context, while workspaces/ stores built-in workspace content shipped with the system.

Workspaces support hot-reloading via filesystem watcher.

Documentation

Use the [Documentation Index](docs/README.md) as the canonical navigation hub. The table below is a curated subset of the most common entrypoints.

| Guide | Description | | ---------------------------------------------- | --------------------------------------------------------- | | [Architecture](docs/reference/architecture.md) | End-to-end message flow and subsystem overview | | [Deployment](docs/reference/deployment.md) | Docker, bare-metal, systemd, reverse proxy, observability | | [Configuration](docs/reference/configuration.md) | Detailed reference for orka.toml and env vars | | [CLI Reference](docs/reference/cli-reference.md) | Current commands and flags exposed by the orka binary | | [Prompt Architecture](docs/guides/agents.md) | Guide to the prompt pipeline, templates, and Workspaces | | [Skill Development](docs/guides/skill-development.md) | Built-in, WASM, and soft skills; eval framework | | [WASM Tutorial](docs/guides/tutorials/build-a-wasm-plugin.md) | Step-by-step guide to writing WebAssembly plugins | | [MCP Guide](docs/reference/mcp-guide.md) | MCP client/server, HTTP transport, OAuth | | [Experience System](docs/guides/experience-system.md) | Self-learning loop, reflection, distillation | | [Eval Framework](docs/guides/eval-guide.md) | TOML scenario runner for offline skill testing | | [Security](SECURITY.md) | Vulnerability reporting, hardening checklist |

Internal-only or preview material lives under docs/internal/ or is explicitly marked as preview when it documents code paths that are not currently exposed by the public CLI.

Companion docs that sit outside docs/ are also indexed from [docs/README.md](docs/README.md), including examples, packaging, SDK, tooling, tests, and selected crate-local READMEs.

Development

# Run all tests
cargo test --workspace

# Run with Redis integration tests
cargo test --workspace -- --ignored

# Check formatting
cargo fmt --all -- --check

# Lint
cargo clippy --workspace --all-targets

CLI

The orka command-line tool provides a full suite of management commands for server administration, agent operations, and observability.

For a complete list of commands and global options, see the [CLI Reference](docs/reference/cli-reference.md).

Project Structure

Curated overview of the main repository areas; this is intentionally not an exhaustive listing of every workspace package.

orka/
├── crates/
│   ├── orka-core/            # Shared types, traits, errors
│   ├── orka-infra/           # Message bus, queue, session, conversation (Redis)
│   ├── orka-auth/            # JWT and API key authentication
│   ├── orka-worker/          # Worker pool & handlers
│   ├── orka-gateway/         # Inbound message gateway
│   ├── orka-observe/         # Domain event observability
│   ├── orka-skills/          # Skill registry & execution
│   ├── orka-coding/          # Coding delegation skills (Claude Cod

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gianlucamazza](https://github.com/gianlucamazza)
- **Source:** [gianlucamazza/orka](https://github.com/gianlucamazza/orka)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.