# Realm documentation

Realm is a workflow engine that an AI agent calls. These pages describe Realm as it is on the `main` branch; the published version is 0.47.0. Where a page shows something added after version 0.46.0, the page says so; it is in 0.47.0 unless the page says otherwise. Every command and output in them came from a run. User names, host names and folders in the outputs may be placeholders, such as `ops@server-1`, `/srv/shop` or `/home/you`.

## Start here

- [What is Realm, and when to use it?](https://realmengine.dev/docs/start/what-is-realm.md)
- [Install and first run](https://realmengine.dev/docs/start/install-and-first-run.md)
- [How a run moves](https://realmengine.dev/docs/start/how-a-run-moves.md)
- [How Realm compares with other workflow tools](https://realmengine.dev/compare/), a page on the website

## Concepts

- [Workflows, steps and the run record](https://realmengine.dev/docs/concepts/workflows-steps-and-runs.md)
- [The four step kinds](https://realmengine.dev/docs/concepts/step-kinds.md)
- [Order and routing](https://realmengine.dev/docs/concepts/order-and-routing.md)
- [Human gates and trust levels](https://realmengine.dev/docs/concepts/gates-and-trust.md)
- [Evidence, and how a run ends](https://realmengine.dev/docs/concepts/evidence.md)
- [Who drives a run](https://realmengine.dev/docs/concepts/who-drives-a-run.md)

## Guides

- [Write your first workflow](https://realmengine.dev/docs/guides/first-workflow.md)
- [Call a service with an adapter](https://realmengine.dev/docs/guides/call-a-service.md)
- [Write an agent step](https://realmengine.dev/docs/guides/agent-steps.md)
- [Give an agent step tools](https://realmengine.dev/docs/guides/agent-tools.md)
- [Add a human gate](https://realmengine.dev/docs/guides/human-gates.md)
- [Write a step handler](https://realmengine.dev/docs/guides/step-handlers.md)
- [Run a workflow with `realm agent`](https://realmengine.dev/docs/guides/realm-agent.md)
- [Connect an MCP client](https://realmengine.dev/docs/guides/connect-an-mcp-client.md)
- [Start runs from webhooks](https://realmengine.dev/docs/guides/webhooks.md)
- [Answer gates from Slack](https://realmengine.dev/docs/guides/slack-gates.md)
- [Handle failure](https://realmengine.dev/docs/guides/handle-failure.md)
- [Start runs safely](https://realmengine.dev/docs/guides/idempotency-and-batches.md)
- [Test a workflow](https://realmengine.dev/docs/guides/test-a-workflow.md)
- [Operate runs](https://realmengine.dev/docs/guides/operate-runs.md)
- [Deploy a project](https://realmengine.dev/docs/guides/deploy.md)
- [Let an assistant plan its own workflow](https://realmengine.dev/docs/guides/agent-created-workflows.md)
- [Upgrade Realm](https://realmengine.dev/docs/guides/upgrade.md)

## Reference: the workflow file

- [Workflow file: top-level fields](https://realmengine.dev/docs/reference/workflow/top-level-fields.md)
- [Workflow file: step fields](https://realmengine.dev/docs/reference/workflow/step-fields.md)
- [Input maps, template expressions and filters](https://realmengine.dev/docs/reference/workflow/input-map-and-templates.md)
- [Conditions: `when`, `preconditions`, `abort_unless`](https://realmengine.dev/docs/reference/workflow/conditions.md)
- [Gates: `trust` and the `gate` block](https://realmengine.dev/docs/reference/workflow/gates.md)
- [Retry and timeouts](https://realmengine.dev/docs/reference/workflow/retry-and-timeouts.md)
- [Agent-step controls](https://realmengine.dev/docs/reference/workflow/agent-step-controls.md)
- [Services, tool servers, step templates, profiles and workflow context](https://realmengine.dev/docs/reference/workflow/services-profiles-and-context.md)
- [Webhook trigger](https://realmengine.dev/docs/reference/workflow/webhook-trigger.md)
- [JSON Schema blocks](https://realmengine.dev/docs/reference/workflow/json-schema-blocks.md)
- [What the loader refuses and warns about](https://realmengine.dev/docs/reference/workflow/loader-diagnostics.md)

## Reference: the command line

- [`realm workflow`](https://realmengine.dev/docs/reference/cli/realm-workflow.md)
- [`realm run`: commands that read](https://realmengine.dev/docs/reference/cli/realm-run-reading.md)
- [`realm run`: commands that act](https://realmengine.dev/docs/reference/cli/realm-run-acting.md)
- [`realm agent`](https://realmengine.dev/docs/reference/cli/realm-agent.md)
- [`realm listen`](https://realmengine.dev/docs/reference/cli/realm-listen.md)
- [`realm mcp` and `realm serve`](https://realmengine.dev/docs/reference/cli/realm-mcp-and-serve.md)

## Reference: MCP

- [MCP tools](https://realmengine.dev/docs/reference/mcp/tools.md)
- [Run state and health findings](https://realmengine.dev/docs/reference/mcp/run-state-and-health.md)

## Reference: code and settings

- [Adapters](https://realmengine.dev/docs/reference/adapters.md)
- [Handlers](https://realmengine.dev/docs/reference/handlers.md)
- [Deployment manifest (`realm.yaml`)](https://realmengine.dev/docs/reference/deployment-manifest.md)
- [Project extensions](https://realmengine.dev/docs/reference/project-extensions.md)
- [Testing package](https://realmengine.dev/docs/reference/testing-package.md)
- [Core library: stores and the store contract](https://realmengine.dev/docs/reference/core-library.md)

## Reference: lookups

- [Error codes](https://realmengine.dev/docs/reference/error-codes.md)
- [Run record and export bundle format](https://realmengine.dev/docs/reference/run-record-and-export.md)
- [Environment variables and files on disk](https://realmengine.dev/docs/reference/environment-and-files.md)
- [Glossary](https://realmengine.dev/docs/reference/glossary.md)