<p align="center"> <img src="docs/public/logo.png" alt="Orloj" width="200" /> </p>

Orloj

Named after the Prague Orloj, an astronomical clock that has coordinated complex mechanisms for over 600 years.

An orchestration runtime for multi-agent AI systems.

Declare your agents, tools, and policies as YAML. Orloj schedules, executes, routes, and governs them so you can run multi-agent systems in production with the same operational rigor you expect from infrastructure.

Status: Orloj is under active development. APIs and resource schemas may change between minor versions before 1.0.

Official SDKs

Call the Orloj HTTP API from application code using the official clients (complementing orlojctl for operators). For REST shapes and generated types, see HTTP API (OpenAPI).

| Language | Install | Links | | ------------ | ------------------------ | ---------------------------------------------------------------------------------------- | | Python | pip install orloj-sdk | PyPI · Repository | | TypeScript | npm install orloj | npm · Repository |

Start here: See Orloj in Action · 5-minute tutorial

Orloj in Action

Orloj is API/CLI-first; the web console is an optional operator UI.

Web Console Walkthrough

These captures are from the web console running the testing/scenarios-real/01-pipeline scenario locally.

Run Lifecycle (GIF)

Watch a full run flow from task creation through running to success in the live frontend.

Dashboard Overview

View the operator dashboard with system status and active workload at a glance.

System Topology

Inspect the agent-system graph topology and understand how nodes connect.

Why Orloj

Running AI agents in production today looks a lot like running containers before container orchestration: ad-hoc scripts, no governance, no observability, and no standard way to manage an agent fleet. Orloj provides:

• Agents-as-Code -- declare agents, their models, tools, and constraints in version-controlled YAML manifests.
• DAG-based orchestration -- pipeline, hierarchical, and swarm-loop topologies with fan-out/fan-in support.
• Model routing -- bind agents to OpenAI, Anthropic, Azure OpenAI, Ollama, and other endpoints. Switch providers without changing agent definitions.
• Tool isolation -- execute tools in containers, WASM sandboxes, or process isolation with configurable timeout and retry.
• Governance built in -- policies, roles, and tool permissions enforced at the execution layer. Unauthorized tool calls fail closed.
• Production reliability -- lease-based task ownership, idempotent replay, capped exponential retry with jitter, and dead-letter handling.
• Web console -- built-in UI with topology views, task inspection, and live event streaming.

Quickstart

Get started in 5 minutes — scaffold with orlojctl init, add your API key, apply manifests, and run a pipeline with orlojctl run.

Install orlojctl (CLI) via Homebrew:

brew tap OrlojHQ/orloj
brew install orlojctl

Formula versions follow Orloj releases.

Or install all binaries (orlojd, orlojworker, orlojctl) with the install script:

curl -sSfL https://raw.githubusercontent.com/OrlojHQ/orloj/main/scripts/install.sh | sh

You can also download binaries manually from GitHub Releases. Then run:

# Start the server with an embedded worker
./orlojd --storage-backend=memory --task-execution-mode=sequential --embedded-worker

Open http://127.0.0.1:8080/ to explore the web console, then apply a starter blueprint. The example manifests live in this repo -- clone it or browse them on GitHub:

# Apply a starter blueprint (pipeline: planner -> research -> writer)
./orlojctl apply -f examples/blueprints/pipeline/ --run

# Check the result
./orlojctl get task bp-pipeline-task

Or build from source (requires Go 1.25+):

go build -o orlojd ./cmd/orlojd
go build -o orlojctl ./cmd/orlojctl

When you are ready to scale, switch to message-driven mode with distributed workers and Postgres persistence. See the Quickstart guide for details. Full walkthrough: 5-minute tutorial.

Architecture

┌─────────────────────────────────────────────────────┐
│                  Server (orlojd)                     │
│                                                     │
│  ┌──────────────┐   ┌────────────────┐              │
│  │  API Server   │──►│ Resource Store  │             │
│  │   (REST)      │   │ mem / postgres  │             │
│  └──────┬───────┘   └────────────────┘              │
│         │                                           │
│         ▼                                           │
│  ┌──────────────┐   ┌────────────────┐              │
│  │   Services    │──►│ Task Scheduler │              │
│  └──────────────┘   └───────┬────────┘              │
└─────────────────────────────┼───────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────┐
│                 Workers (orlojworker)                │
│                                                     │
│  ┌──────────────┐   ┌───────────────┐               │
│  │  Task Worker  │──►│ Model Gateway │               │
│  │              │   └───────────────┘               │
│  │              │──►┌───────────────┐               │
│  │              │   │  Tool Runtime  │               │
│  │              │   └───────────────┘               │
│  │       ◄──────┼───┌───────────────┐               │
│  │              │──►│  Message Bus   │               │
│  └──────────────┘   └───────────────┘               │
└─────────────────────────────────────────────────────┘

Server (orlojd) -- API server, resource store (in-memory or Postgres), background services, and task scheduler.

Workers (orlojworker) -- claim tasks, execute agent graphs, route model requests, run tools, and handle inter-agent messaging.

Governance -- AgentPolicy, AgentRole, and ToolPermission resources enforced inline during every tool call and model interaction.

Persistence is backed by Postgres (or in-memory for local dev). Message-driven mode uses NATS JetStream for durable agent-to-agent messaging.

HTTP API (OpenAPI)

The v1 REST API is described in openapi/openapi.yaml (OpenAPI 3.1). Shared request/response models live under openapi/schemas/; the root file is generated by openapi/build_openapi.py (python3 openapi/build_openapi.py). CI runs npx @redocly/cli lint openapi/openapi.yaml. Contributors: see Contributing — OpenAPI for what to edit and what not to hand-edit.

Resources

Orloj manages 15 resource types, all defined as declarative YAML with apiVersion, kind, metadata, spec, and status fields:

Core

| Resource | Purpose | | ------------- | ---------------------------------------------------- | | Agent | Unit of work backed by a language model | | AgentSystem | Directed graph composing multiple agents | | ModelEndpoint | Connection to a model provider | | Tool | External capability with isolation and retry | | Secret | Credential storage | | Memory | Vector-backed retrieval for agents | | McpServer | MCP server connection that discovers/syncs MCP tools |

Governance

| Resource | Purpose | | -------------- | ------------------------------------------ | | AgentPolicy | Token, model, and tool constraints | | AgentRole | Named permission set bound to agents | | ToolPermission | Required permissions for tool invocation | | ToolApproval | Approval record for gated tool invocations |

Scheduling & Triggers

| Resource | Pu