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.
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 is API/CLI-first; the web console is an optional operator UI.
These captures are from the web console running the testing/scenarios-real/01-pipeline scenario locally.
Watch a full run flow from task creation through running to success in the live frontend.
View the operator dashboard with system status and active workload at a glance.
Inspect the agent-system graph topology and understand how nodes connect.
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.
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 orlojctlFormula 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 | shYou 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-workerOpen 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-taskOr build from source (requires Go 1.25+):
go build -o orlojd ./cmd/orlojd
go build -o orlojctl ./cmd/orlojctlWhen 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.
┌─────────────────────────────────────────────────────┐
│ 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.
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.
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 | Purpose |
|---|---|
| Task | Request to execute an AgentSystem |
| TaskSchedule | Cron-based task creation |
| TaskWebhook | Event-triggered task creation |
| Worker | Execution unit with capability declaration |
Drill into a task to see node-level execution state and graph progress.
Open trace and log detail to debug runtime behavior without leaving the task view.
Browse docs.orloj.dev.
- Changelog -- notable changes by release
- 5-minute tutorial -- scaffold, model key, first run
- Getting Started -- install, quickstart
- Concepts -- architecture, agents, tasks, tools, model routing, governance
- Guides -- deploy a pipeline, configure routing, build tools, set up governance
- Deploy & Operate -- local, VPS, Kubernetes, remote CLI access
- Reference -- CLI, API, resource schemas
- Security -- control plane API tokens, secrets, tool isolation
- Examples -- per-kind YAML under
examples/resources/, starterblueprints/, anduse-cases/(in this repo)
Run the full stack (Postgres + server + 2 workers) with Docker Compose:
docker compose up --build -d
docker compose psThe Compose images include the server and workers only. To drive the API from your machine, install orlojctl:
brew tap OrlojHQ/orloj
brew install orlojctlOr via the install script:
curl -sSfL https://raw.githubusercontent.com/OrlojHQ/orloj/main/scripts/install.sh | ORLOJ_BINARIES="orlojctl" shYou can also download it from GitHub Releases. See Deploy & Operate for more details.
See CONTRIBUTING.md for environment setup, test matrix, and PR lifecycle details.