{"id":47680125,"url":"https://github.com/orlojhq/orloj","last_synced_at":"2026-04-21T05:01:33.139Z","repository":{"id":346950780,"uuid":"1182022527","full_name":"OrlojHQ/orloj","owner":"OrlojHQ","description":"An orchestration runtime for multi-agent AI systems. Declare agents, tools, and policies as YAML; Orloj schedules, executes, routes, and governs them for production-grade operation.","archived":false,"fork":false,"pushed_at":"2026-04-21T03:03:16.000Z","size":3576,"stargazers_count":79,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-21T04:42:40.892Z","etag":null,"topics":["agent-framework","agentic-ai","agentic-orchestration","ai","ai-agents","ai-governance","ai-safety","declarative","guardrails","infrastructure-as-code","llm","llmops","mlops","multi-agent","open-source","orchestration","platform-engineering","workflow-orchestration","yaml"],"latest_commit_sha":null,"homepage":"https://orloj.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OrlojHQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["kswiss93"]}},"created_at":"2026-03-14T23:50:50.000Z","updated_at":"2026-04-21T03:02:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"c2ebc1e1-125c-4c1c-a6bd-aa156bd562f2","html_url":"https://github.com/OrlojHQ/orloj","commit_stats":null,"previous_names":["orlojhq/orloj"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/OrlojHQ/orloj","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrlojHQ%2Forloj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrlojHQ%2Forloj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrlojHQ%2Forloj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrlojHQ%2Forloj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OrlojHQ","download_url":"https://codeload.github.com/OrlojHQ/orloj/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrlojHQ%2Forloj/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32077837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agentic-ai","agentic-orchestration","ai","ai-agents","ai-governance","ai-safety","declarative","guardrails","infrastructure-as-code","llm","llmops","mlops","multi-agent","open-source","orchestration","platform-engineering","workflow-orchestration","yaml"],"created_at":"2026-04-02T13:57:02.093Z","updated_at":"2026-04-21T05:01:33.134Z","avatar_url":"https://github.com/OrlojHQ.png","language":"Go","funding_links":["https://github.com/sponsors/kswiss93"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/public/logo.png\" alt=\"Orloj\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n# Orloj\n\n_Named after the [Prague Orloj](https://en.wikipedia.org/wiki/Prague_astronomical_clock), an astronomical clock that has coordinated complex mechanisms for over 600 years._\n\n[![Release](https://img.shields.io/github/v/release/OrlojHQ/orloj?display_name=tag\u0026sort=semver)](https://github.com/OrlojHQ/orloj/releases)\n[![CI](https://img.shields.io/github/actions/workflow/status/OrlojHQ/orloj/ci.yml?branch=main\u0026label=ci)](https://github.com/OrlojHQ/orloj/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/github/actions/workflow/status/OrlojHQ/orloj/docs.yml?branch=main\u0026label=docs)](https://docs.orloj.dev)\n[![Go Report Card](https://goreportcard.com/badge/github.com/OrlojHQ/orloj)](https://goreportcard.com/report/github.com/OrlojHQ/orloj)\n[![Go Reference](https://pkg.go.dev/badge/github.com/OrlojHQ/orloj.svg)](https://pkg.go.dev/github.com/OrlojHQ/orloj)\n[![PyPI - orloj-sdk](https://img.shields.io/pypi/v/orloj-sdk)](https://pypi.org/project/orloj-sdk/)\n[![npm - orloj](https://img.shields.io/npm/v/orloj)](https://www.npmjs.com/package/orloj)\n[![License](https://img.shields.io/github/license/OrlojHQ/orloj)](LICENSE)\n\n**An orchestration runtime for multi-agent AI systems.**\n\nDeclare 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.\n\n\u003e **Status:** Orloj is under active development. APIs and resource schemas may change between minor versions before 1.0.\n\n### Official SDKs\n\nCall 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)](#http-api-openapi).\n\n| Language     | Install                  | Links                                                                                    |\n| ------------ | ------------------------ | ---------------------------------------------------------------------------------------- |\n| Python       | `pip install orloj-sdk`  | [PyPI](https://pypi.org/project/orloj-sdk/) · [Repository](https://github.com/OrlojHQ/orloj-python-sdk) |\n| TypeScript   | `npm install orloj`      | [npm](https://www.npmjs.com/package/orloj) · [Repository](https://github.com/OrlojHQ/orloj-js-sdk)      |\n\n**Start here:** [See Orloj in Action](#orloj-in-action) · [5-minute tutorial](https://docs.orloj.dev/guides/five-minute-tutorial)\n\n## Orloj in Action\n\nOrloj is API/CLI-first; the web console is an optional operator UI.\n\n### Web Console Walkthrough\n\nThese captures are from the web console running the `testing/scenarios-real/01-pipeline` scenario locally.\n\n### Run Lifecycle (GIF)\n\n![Orloj task lifecycle animation](docs/public/readme/task-run-lifecycle.gif)\n\nWatch a full run flow from task creation through running to success in the live frontend.\n\n### Dashboard Overview\n\n![Orloj dashboard overview](docs/public/readme/dashboard-overview.png)\n\nView the operator dashboard with system status and active workload at a glance.\n\n### System Topology\n\n![Orloj system topology view](docs/public/readme/system-topology.png)\n\nInspect the agent-system graph topology and understand how nodes connect.\n\n## Why Orloj\n\nRunning 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:\n\n- **Agents-as-Code** -- declare agents, their models, tools, and constraints in version-controlled YAML manifests.\n- **DAG-based orchestration** -- pipeline, hierarchical, and swarm-loop topologies with fan-out/fan-in support.\n- **Model routing** -- bind agents to OpenAI, Anthropic, Azure OpenAI, Ollama, and other endpoints. Switch providers without changing agent definitions.\n- **Tool isolation** -- execute tools in containers, WASM sandboxes, or process isolation with configurable timeout and retry.\n- **Governance built in** -- policies, roles, and tool permissions enforced at the execution layer. Unauthorized tool calls fail closed.\n- **Production reliability** -- lease-based task ownership, idempotent replay, capped exponential retry with jitter, and dead-letter handling.\n- **Web console** -- built-in UI with topology views, task inspection, and live event streaming.\n\n## Quickstart\n\n**[Get started in 5 minutes](https://docs.orloj.dev/guides/five-minute-tutorial)** — scaffold with `orlojctl init`, add your API key, apply manifests, and run a pipeline with `orlojctl run`.\n\nInstall **orlojctl** (CLI) via Homebrew:\n\n```bash\nbrew tap OrlojHQ/orloj\nbrew install orlojctl\n```\n\nFormula versions follow [Orloj releases](https://github.com/OrlojHQ/orloj/releases).\n\nOr install all binaries (**orlojd**, **orlojworker**, **orlojctl**) with the install script:\n\n```bash\ncurl -sSfL https://raw.githubusercontent.com/OrlojHQ/orloj/main/scripts/install.sh | sh\n```\n\nYou can also download binaries manually from [GitHub Releases](https://github.com/OrlojHQ/orloj/releases). Then run:\n\n```bash\n# Start the server with an embedded worker\n./orlojd --storage-backend=memory --task-execution-mode=sequential --embedded-worker\n```\n\nOpen **[http://127.0.0.1:8080/](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](https://github.com/OrlojHQ/orloj/tree/main/examples):\n\n```bash\n# Apply a starter blueprint (pipeline: planner -\u003e research -\u003e writer)\n./orlojctl apply -f examples/blueprints/pipeline/ --run\n\n# Check the result\n./orlojctl get task bp-pipeline-task\n```\n\nOr build from source (requires Go 1.25+):\n\n```bash\ngo build -o orlojd ./cmd/orlojd\ngo build -o orlojctl ./cmd/orlojctl\n```\n\nWhen you are ready to scale, switch to message-driven mode with distributed workers and Postgres persistence. See the [Quickstart guide](https://docs.orloj.dev/getting-started/quickstart#scaling-to-production) for details. Full walkthrough: [5-minute tutorial](https://docs.orloj.dev/guides/five-minute-tutorial).\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                  Server (orlojd)                     │\n│                                                     │\n│  ┌──────────────┐   ┌────────────────┐              │\n│  │  API Server   │──►│ Resource Store  │             │\n│  │   (REST)      │   │ mem / postgres  │             │\n│  └──────┬───────┘   └────────────────┘              │\n│         │                                           │\n│         ▼                                           │\n│  ┌──────────────┐   ┌────────────────┐              │\n│  │   Services    │──►│ Task Scheduler │              │\n│  └──────────────┘   └───────┬────────┘              │\n└─────────────────────────────┼───────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────┐\n│                 Workers (orlojworker)                │\n│                                                     │\n│  ┌──────────────┐   ┌───────────────┐               │\n│  │  Task Worker  │──►│ Model Gateway │               │\n│  │              │   └───────────────┘               │\n│  │              │──►┌───────────────┐               │\n│  │              │   │  Tool Runtime  │               │\n│  │              │   └───────────────┘               │\n│  │       ◄──────┼───┌───────────────┐               │\n│  │              │──►│  Message Bus   │               │\n│  └──────────────┘   └───────────────┘               │\n└─────────────────────────────────────────────────────┘\n```\n\n**Server** (`orlojd`) -- API server, resource store (in-memory or Postgres), background services, and task scheduler.\n\n**Workers** (`orlojworker`) -- claim tasks, execute agent graphs, route model requests, run tools, and handle inter-agent messaging.\n\n**Governance** -- AgentPolicy, AgentRole, and ToolPermission resources enforced inline during every tool call and model interaction.\n\nPersistence is backed by Postgres (or in-memory for local dev). Message-driven mode uses NATS JetStream for durable agent-to-agent messaging.\n\n## HTTP API (OpenAPI)\n\nThe v1 REST API is described in [openapi/openapi.yaml](openapi/openapi.yaml) (OpenAPI 3.1). Shared request/response models live under [openapi/schemas/](openapi/schemas/); the root file is **generated** by [openapi/build_openapi.py](openapi/build_openapi.py) (`python3 openapi/build_openapi.py`). CI runs `npx @redocly/cli lint openapi/openapi.yaml`. Contributors: see [Contributing — OpenAPI](CONTRIBUTING.md#openapi) for what to edit and what not to hand-edit.\n\n## Resources\n\nOrloj manages 15 resource types, all defined as declarative YAML with `apiVersion`, `kind`, `metadata`, `spec`, and `status` fields:\n\n**Core**\n\n\n| Resource      | Purpose                                              |\n| ------------- | ---------------------------------------------------- |\n| Agent         | Unit of work backed by a language model              |\n| AgentSystem   | Directed graph composing multiple agents             |\n| ModelEndpoint | Connection to a model provider                       |\n| Tool          | External capability with isolation and retry         |\n| Secret        | Credential storage                                   |\n| Memory        | Vector-backed retrieval for agents                   |\n| McpServer     | MCP server connection that discovers/syncs MCP tools |\n\n\n**Governance**\n\n\n| Resource       | Purpose                                    |\n| -------------- | ------------------------------------------ |\n| AgentPolicy    | Token, model, and tool constraints         |\n| AgentRole      | Named permission set bound to agents       |\n| ToolPermission | Required permissions for tool invocation   |\n| ToolApproval   | Approval record for gated tool invocations |\n\n\n**Scheduling \u0026 Triggers**\n\n\n| Resource     | Purpose                                    |\n| ------------ | ------------------------------------------ |\n| Task         | Request to execute an AgentSystem          |\n| TaskSchedule | Cron-based task creation                   |\n| TaskWebhook  | Event-triggered task creation              |\n| Worker       | Execution unit with capability declaration |\n\n\n## More Screenshots\n\n### Task Detail and Graph\n\n![Orloj task detail graph view](docs/public/readme/task-detail-graph.png)\n\nDrill into a task to see node-level execution state and graph progress.\n\n### Trace and Logs\n\n![Orloj task trace and logs view](docs/public/readme/task-trace-logs.png)\n\nOpen trace and log detail to debug runtime behavior without leaving the task view.\n\n## Documentation\n\nBrowse **[docs.orloj.dev](https://docs.orloj.dev)**.\n\n- [Changelog](CHANGELOG.md) -- notable changes by release\n- [5-minute tutorial](https://docs.orloj.dev/guides/five-minute-tutorial) -- scaffold, model key, first run\n- [Getting Started](https://docs.orloj.dev/getting-started/install) -- install, quickstart\n- [Concepts](https://docs.orloj.dev/concepts/architecture) -- architecture, agents, tasks, tools, model routing, governance\n- [Guides](https://docs.orloj.dev/guides/) -- deploy a pipeline, configure routing, build tools, set up governance\n- [Deploy \u0026 Operate](https://docs.orloj.dev/deploy/) -- local, VPS, Kubernetes, [remote CLI access](https://docs.orloj.dev/deploy/remote-cli-access)\n- [Reference](https://docs.orloj.dev/reference/cli) -- CLI, API, resource schemas\n- [Security](https://docs.orloj.dev/operations/security) -- control plane API tokens, secrets, tool isolation\n- [Examples](examples/README.md) -- per-kind YAML under `examples/resources/`, starter `blueprints/`, and `use-cases/` (in this repo)\n\n## Docker Compose\n\nRun the full stack (Postgres + server + 2 workers) with Docker Compose:\n\n```bash\ndocker compose up --build -d\ndocker compose ps\n```\n\nThe Compose images include the server and workers only. To drive the API from your machine, install **`orlojctl`**:\n\n```bash\nbrew tap OrlojHQ/orloj\nbrew install orlojctl\n```\n\nOr via the install script:\n\n```bash\ncurl -sSfL https://raw.githubusercontent.com/OrlojHQ/orloj/main/scripts/install.sh | ORLOJ_BINARIES=\"orlojctl\" sh\n```\n\nYou can also download it from [GitHub Releases](https://github.com/OrlojHQ/orloj/releases). See [Deploy \u0026 Operate](https://docs.orloj.dev/deploy/) for more details.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup, test matrix, and PR lifecycle details.\n\n- [Good first issue](https://github.com/OrlojHQ/orloj/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)\n- [Help wanted](https://github.com/OrlojHQ/orloj/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22)\n- [Use-case contribution guide](examples/use-cases/CONTRIBUTING.md)\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forlojhq%2Forloj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forlojhq%2Forloj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forlojhq%2Forloj/lists"}