# Orloj Docs

> Runtime, governance, and orchestration for agent systems.

## Docs

- [A2A JSON-RPC](/reference/a2a-jsonrpc): **Stability: beta** -- A2A protocol support ships with `orloj.dev/v1`. The JSON-RPC interface follows the [A2A specification](https://github.com/a2aproject/A2A) and may evolve as the spec matures.
- [API Reference](/reference/api): **Stability: beta** -- This API surface ships with `orloj.dev/v1` and is suitable for production use, but may evolve with migration guidance in future minor releases.
- [CLI Reference](/reference/cli): `orlojctl` is the command-line interface for managing Orloj resources, running tasks, and inspecting system state.
- [Glossary](/reference/glossary): Canonical definitions for terms used throughout Orloj documentation.
- [Reference](/reference): Detailed schemas and interfaces for API consumers and platform engineers.
- [Internal Tools](/reference/internal-tools): Flag reference for `orloj-loadtest` (reliability/load harness) and `orloj-alertcheck` (alert profile evaluator). These are operational and CI tools, not user-facing CLIs.
- [Server Flags](/reference/server-flags): Flag reference for the `orlojd` (API server) and `orlojworker` (task worker) daemon binaries.
- [Agent Card](/reference/resources/agent-card): **Stability: beta** -- Agent Cards are generated resources that follow the [A2A specification](https://github.com/a2aproject/A2A). The schema may evolve as the A2A spec matures.
- [AgentPolicy](/reference/resources/agent-policy): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [AgentRole](/reference/resources/agent-role): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [AgentSystem](/reference/resources/agent-system): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Agent](/reference/resources/agent): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [ContextAdapter](/reference/resources/context-adapter): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [EvalDataset](/reference/resources/eval-dataset): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [EvalRun](/reference/resources/eval-run): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Resources](/reference/resources): This section documents selected resource kinds in `orloj.dev/v1`, based on the runtime types and normalization logic in:
- [McpServer](/reference/resources/mcp-server): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Memory](/reference/resources/memory): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [ModelEndpoint](/reference/resources/model-endpoint): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [SealedSecret](/reference/resources/sealed-secret): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Secret](/reference/resources/secret): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [TaskApproval](/reference/resources/task-approval): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [TaskSchedule](/reference/resources/task-schedule): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [TaskWebhook](/reference/resources/task-webhook): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Task](/reference/resources/task): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [ToolApproval](/reference/resources/tool-approval): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [ToolPermission](/reference/resources/tool-permission): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Tool](/reference/resources/tool): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Worker](/reference/resources/worker): **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.
- [Backup and Restore](/operations/backup-restore): This guide covers backup and restore procedures for Orloj deployments using the Postgres storage backend. Memory-backend deployments are ephemeral and do not require backup.
- [Configuration](/operations/configuration): This page is the canonical reference for runtime environment variables and flag-to-env precedence for `orlojd`, `orlojworker`, and `orlojctl`.
- [Monitoring and Alerts](/operations/monitoring-alerts): Use `orloj-alertcheck` and dashboard contracts to validate runtime reliability signals.
- [Observability](/operations/observability): Orloj provides built-in observability through OpenTelemetry tracing, Prometheus metrics, structured logging, and an in-app trace visualization UI. These features work out of the box in OSS deployments and integrate with standard observability backends.
- [Operations Runbook](/operations/runbook): Use this runbook for baseline production operation and incident response.
- [Security and Isolation](/operations/security): This page describes current runtime security controls and expected operator practices.
- [Task Scheduling (Cron)](/operations/task-scheduling): Use `TaskSchedule` to create recurring run tasks from a task template.
- [Threat Model](/operations/threat-model): This page consolidates Orloj's security design: trust boundaries, the attacker model it defends against, the controls at each boundary, and the residual risks operators must own. It is a companion to [Security and Isolation](./security.md), which documents each control in depth.
- [Troubleshooting](/operations/troubleshooting): Use this page for deterministic diagnosis and remediation of common failures.
- [Upgrades and Rollbacks](/operations/upgrades): This guide defines safe upgrade and rollback procedures for the Orloj server and workers.
- [Webhook Triggers](/operations/webhooks): Use `TaskWebhook` to trigger task runs from signed external HTTP events.
- [Expose AgentSystems via A2A](/guides/a2a-expose-agents): This guide walks through exposing selected Orloj AgentSystems to external A2A clients.
- [Use Remote A2A Agents](/guides/a2a-remote-agents): This guide walks through configuring Orloj to call external A2A agents as tools. Remote A2A agents appear as regular tools in your agent's toolset -- the A2A protocol details are handled transparently by the runtime.
- [Build a Custom Tool](/guides/build-custom-tool): This guide is for developers who need to extend agent capabilities by implementing a custom tool. You will implement the Tool Contract v1, register the tool as a resource, configure isolation and retry, and validate it with the conformance harness.
- [Build a WASM Tool](/guides/build-wasm-tool): This guide walks through building and deploying a WebAssembly tool that agents can invoke through Orloj's embedded wazero runtime. WASM tools execute in-process with host-enforced resource limits -- no external runtime binary required.
- [Configure Model Routing](/guides/configure-model-routing): This guide is for platform engineers who need to route agents to different model providers. You will set up ModelEndpoints for multiple providers, bind agents to endpoints by reference, and verify that requests route correctly.
- [Connect an MCP Server](/guides/connect-mcp-server): This guide is for platform engineers who want to connect external MCP (Model Context Protocol) servers to Orloj. You will register an MCP server, verify tool discovery, selectively import tools, and assign them to agents.
- [Deploy Your First Pipeline](/guides/deploy-pipeline): This guide is for platform engineers who want to run a multi-agent pipeline end-to-end. You will define three agents, wire them into a sequential graph, submit a task, and inspect the results.
- [Your First Agent System in 5 Minutes](/guides/five-minute-tutorial): This tutorial walks you through a three-agent **pipeline**: planner → research → writer. You will go from an empty directory to a running task with real model calls, using the web console to watch progress.
- [Human Review Checkpoints](/guides/human-review-checkpoints): This guide shows how to pause an Orloj workflow for human review of agent output or final task output.
- [Guides](/guides): Step-by-step tutorials for common Orloj workflows.
- [kubectl vs orlojctl — Which Tool Do I Use?](/guides/kubectl-vs-orlojctl): When the [CRD operator](../deploy/kubernetes-operator.md) is deployed, Orloj resources live as real Kubernetes CRDs. This means `kubectl` can handle basic CRUD — but `orlojctl` remains the primary tool for operations, runtime control, and admin tasks.
- [Capture README Orloj in Action Media](/guides/readme-media-capture): This guide documents the reproducible workflow for generating the README media assets used in the **Orloj in Action** section.
- [Run Your First Agent Evaluation](/guides/run-agent-evaluation): This guide walks you through creating a golden dataset, running an evaluation against an agent system, and comparing results across different configurations. By the end, you will have a repeatable evaluation workflow for measuring agent quality.
- [Set Up Multi-Agent Governance](/guides/setup-governance): This guide is for platform engineers who need to enforce tool authorization and model constraints on their agent systems. You will create policies, roles, and tool permissions, deploy a governed agent system, and verify that unauthorized tool calls are denied.
- [Starter Blueprints](/guides/starter-blueprints): Blueprints are ready-to-run templates that combine agents, an agent system (the graph), and a task into a single directory. They are the fastest way to see Orloj in action and to understand each orchestration pattern.
- [Core Concepts](/getting-started/core-concepts): This page introduces Orloj's key building blocks and how they fit together. Read this before diving into the individual concept pages.
- [Install Orloj](/getting-started/install): This guide covers how to install Orloj for local evaluation and production-like use: from source (clone and run or build), from **release binaries** (GitHub Releases), or from **container images** (GitHub Container Registry). Use release artifacts when you want a tagged, published build instead of building from source.
- [Quickstart](/getting-started/quickstart): Get a multi-agent pipeline running in under five minutes. This quickstart uses sequential execution mode -- the simplest way to run Orloj with a single process and no external dependencies.
- [Deploy and Operate](/deploy): This section covers deploying Orloj to any environment and running it in production.
- [Kubernetes CRD Operator](/deploy/kubernetes-operator): The CRD sync operator is an **optional** component that makes Orloj resources (Agents, AgentSystems, Tools, etc.) real Kubernetes Custom Resource Definitions. When deployed, you can manage Orloj configuration with `kubectl apply`, store manifests in Git, and let Argo CD or Flux reconcile them — the operator watches CRD objects and syncs them into the Orloj Postgres store automatically.
- [Kubernetes Deployment (Helm + Manifest Fallback)](/deploy/kubernetes): Deploy Orloj on Kubernetes with a Helm chart (recommended) or with raw manifests (fallback).
- [Local Deployment](/deploy/local): Run Orloj locally for development and deterministic feature validation.
- [Remote CLI and API access](/deploy/remote-cli-access): This guide is for **operators and users** who already have `orlojd` reachable on a network (self-hosted, VPS, Kubernetes, or internal URL) and need to call the API from **`orlojctl`**, scripts, or CI. It complements the [quickstart](../getting-started/quickstart.md), which focuses on a single-machine dev loop.
- [VPS Deployment (Compose + systemd)](/deploy/vps): Run Orloj on a single VPS with Docker Compose managed by systemd for automatic restart and reboot recovery.
- [A2A Interoperability](/concepts/a2a-interoperability): Orloj implements the [Agent-to-Agent (A2A) protocol](https://github.com/a2aproject/A2A) to enable cross-platform agent communication. Any A2A-compliant client can discover Orloj agents, submit tasks, and stream results -- and Orloj agents can call external A2A agents as tools.
- [Architecture Overview](/concepts/architecture): Orloj is organized into three layers: a **server** that manages resources and scheduling, **workers** that execute agent workflows, and a **governance layer** that enforces policies and permissions at runtime.
- [Execution and Messaging](/concepts/execution-model): This page documents task routing, message lifecycle, and ownership guarantees.
- [Define a CLI Tool](/concepts/tools/cli-tool): This guide shows how to define a CLI tool that invokes a local binary (e.g., `kubectl`, `gh`, `aws`) under Orloj's governance and isolation model.
- [McpServer](/concepts/tools/mcp-server): An **McpServer** represents a connection to an external MCP (Model Context Protocol) server. The McpServer controller discovers tools via `tools/list` and auto-generates [Tool](./tool.md) resources (type=mcp) for each discovered tool.
- [ModelEndpoint](/concepts/tools/model-endpoint): Orloj decouples agents from specific model providers through **ModelEndpoint** resources. A ModelEndpoint declares a provider, base URL, default model, and authentication -- and agents reference it by name. This lets you swap providers, manage credentials centrally, and route different agents to different models without modifying agent manifests.
- [Orloj Built-in Tools](/concepts/tools/orloj-tools): Orloj provides built-in tools under the `orloj.*` namespace that let agents interact with the Orloj control plane. These tools follow the same governance model as any other tool -- ToolPermission, AgentPolicy `blocked_tools`, and ToolApproval all apply.
- [Secret](/concepts/tools/secret): A **Secret** stores sensitive values (API keys, tokens, passwords) used by other resources. ModelEndpoints, Tools, McpServers, and TaskWebhooks reference Secrets for authentication.
- [Tool](/concepts/tools/tool): A **Tool** is an external capability that agents can invoke during execution. Orloj provides a standardized tool contract, multiple isolation backends, and runtime controls for timeout, retry, and risk classification.
- [TaskSchedule](/concepts/tasks/task-schedule): A **TaskSchedule** creates [Tasks](./task.md) on a cron-based schedule from a template task. Use this to automate recurring work like daily reports, periodic data processing, or scheduled monitoring runs.
- [TaskWebhook](/concepts/tasks/task-webhook): A **TaskWebhook** creates [Tasks](./task.md) in response to external HTTP events, with built-in signature verification and idempotency.
- [Task](/concepts/tasks/task): A **Task** is a request to execute an [AgentSystem](../agents/agent-system.md). Tasks are the unit of work in Orloj -- they carry input, track execution state, and produce output.
- [Memory](/concepts/memory): Memory gives agents the ability to store, retrieve, and search information across execution steps and across tasks. Orloj implements memory as a layered system: conversation history provides short-term context within a single task turn, a task-scoped shared store lets agents in the same task exchange state, and persistent backends retain knowledge across task runs.
- [Memory Providers](/concepts/memory/providers): Memory providers are the backends that store and retrieve data for Orloj's built-in memory tools. There are two paths to connect a vector database, both coexisting:
- [Worker](/concepts/infrastructure/worker): A **Worker** is an execution unit that claims and runs [Tasks](../tasks/task.md). Workers register their capabilities (region, GPU, supported models) and the scheduler uses these for task matching.
- [AgentPolicy](/concepts/governance/agent-policy): An **AgentPolicy** sets execution constraints on agent systems or tasks. Policies can restrict model usage, block specific tools, and cap token consumption.
- [AgentRole](/concepts/governance/agent-role): An **AgentRole** is a named set of permission strings. Agents bind to roles through their `spec.roles` field, which grants them the associated permissions.
- [Governance and Policies](/concepts/governance): Orloj provides a built-in governance layer that controls what agents can do at runtime. Three resource types work together to enforce authorization: **[AgentPolicy](./agent-policy.md)** constrains execution parameters, **[AgentRole](./agent-role.md)** grants named permissions to agents, and **[ToolPermission](./tool-permission.md)** defines what permissions are required to invoke a tool.
- [TaskApproval](/concepts/governance/task-approval): `TaskApproval` extends Orloj approvals from "may this tool call happen?" to "is this output safe and acceptable to continue?"
- [ToolApproval](/concepts/governance/tool-approval): A **ToolApproval** captures a pending human/system approval request for a tool invocation that was flagged by a [ToolPermission](./tool-permission.md) `operation_rules` verdict of `approval_required`.
- [ToolPermission](/concepts/governance/tool-permission): A **ToolPermission** defines what permissions are required to invoke a specific [Tool](../tools/tool.md). When an agent attempts to call a tool, the runtime checks the agent's accumulated permissions against the tool's ToolPermission.
- [Agent Evaluation](/concepts/evaluation): Orloj includes a built-in evaluation framework for measuring and comparing agent system quality. Define golden datasets as declarative YAML, run them against your agent systems, score the results with multiple strategies (programmatic, LLM-as-judge, or human review), and compare runs side-by-side.
- [AgentSystem](/concepts/agents/agent-system): An **AgentSystem** composes multiple [Agents](./agent.md) into a directed graph that Orloj executes as a coordinated workflow. The graph defines how messages flow between agents during task execution.
- [Agent](/concepts/agents/agent): An **Agent** is a declarative unit of work backed by a language model. It defines what the agent does (its prompt), what model powers it, what tools it can call, and what constraints bound its execution.