# Realm

> The workflow engine your AI agent calls over MCP. Steps run in order; answers that break their schema are refused.

Realm is an open-source workflow engine (Apache-2.0) for AI agents, published by Sensigo Software. An agent calls it through its MCP server, `@sensigo/realm-mcp`, or `realm agent` drives a model from the command line. Realm decides which steps may run next, refuses an answer that breaks the JSON Schema its step declares, pauses the run at a human gate until someone answers it or its time limit runs out, and records each finished step's output with a SHA-256 hash in a run record you can inspect, export and compare. It is not MongoDB's Realm mobile database or any other product named Realm. Install the command line with `npm install -g @sensigo/realm-cli`.

Each docs page below links to its Markdown copy. The page itself is at the same address with a closing slash in place of `.md`. The docs index is https://realmengine.dev/docs.md.

## Start here

- [What is Realm, and when to use it?](https://realmengine.dev/docs/start/what-is-realm.md): Realm is a workflow engine that an AI agent calls, and it accepts each result only if it fits the step's rules. What that gives you, and when to use it.
- [Install and first run](https://realmengine.dev/docs/start/install-and-first-run.md): Install Realm and finish a first run with no AI model and no account: you play the model, watch Realm refuse a wrong answer, and read the record.
- [How a run moves](https://realmengine.dev/docs/start/how-a-run-moves.md): How a Realm run moves one step at a time: which steps Realm runs itself, which need a model or a person, and the ways a run can be driven.

## Concepts

- [Workflows, steps and the run record](https://realmengine.dev/docs/concepts/workflows-steps-and-runs.md): The workflow file, the registered copy, the run and the run record: what each one is, how they relate, and which one a command reads or changes.
- [The four step kinds](https://realmengine.dev/docs/concepts/step-kinds.md): The four values of a step's execution field (auto, agent, guard and finalizer): what each kind is for, what it records, and how to choose.
- [Order and routing](https://realmengine.dev/docs/concepts/order-and-routing.md): How Realm decides which steps may run after every result, explained through the fields that control it and several runs of one workflow.
- [Human gates and trust levels](https://realmengine.dev/docs/concepts/gates-and-trust.md): How a human gate stops a run until someone answers: how it opens, what the agent can do while it is open, who can answer, and what happens if nobody does.
- [Evidence, and how a run ends](https://realmengine.dev/docs/concepts/evidence.md): What a run's record holds: each step's input and output, why a step was skipped, and what ended the run. How to read it, and what it does and does not prove.
- [Who drives a run](https://realmengine.dev/docs/concepts/who-drives-a-run.md): A run moves only when something calls the engine and hands in each agent step's answer. The drivers Realm offers, and how to choose one.

## Guides

- [Write your first workflow](https://realmengine.dev/docs/guides/first-workflow.md): Write a first workflow with a parameter, two agent steps that pass work between them and one automatic step, then run it by hand and read its record.
- [Call a service with an adapter](https://realmengine.dev/docs/guides/call-a-service.md): Make an auto step do real work through an adapter, such as reading a file or calling an API, pass the result to a later step, and place the credentials.
- [Write an agent step](https://realmengine.dev/docs/guides/agent-steps.md): Write an agent step that hands work to a model and accepts the answer only if it has the right shape: the task, the schema, a profile and the closing text.
- [Give an agent step tools](https://realmengine.dev/docs/guides/agent-tools.md): Give an agent step tools from a tool server, limit how much it may use them, and read what Realm records about each call.
- [Add a human gate](https://realmengine.dev/docs/guides/human-gates.md): Add a point where a person must decide before anything takes effect: a gate with your own choices and message, a step for one choice, and a time limit.
- [Write a step handler](https://realmengine.dev/docs/guides/step-handlers.md): Write a handler, a function from your project that an auto step runs: read its input and settings, then return a result, fail, or stop the run.
- [Run a workflow with realm agent](https://realmengine.dev/docs/guides/realm-agent.md): Run a workflow from start to end with realm agent and a model provider: a full run, what happens when the model answers wrongly, and resuming a stopped run.
- [Connect an MCP client](https://realmengine.dev/docs/guides/connect-an-mcp-client.md): Connect an AI assistant to Realm's MCP server so that it can run your workflows and is held to their rules, and see the calls it makes to drive a run.
- [Start runs from webhooks](https://realmengine.dev/docs/guides/webhooks.md): Start a workflow from an HTTP request: accept a webhook, check that it is genuine, turn its contents into run parameters, and ignore repeats.
- [Answer gates from Slack](https://realmengine.dev/docs/guides/slack-gates.md): Make realm agent post each human gate to a Slack channel and take the answer from a reply in the thread, so a person approves or rejects from Slack.
- [Handle failure](https://realmengine.dev/docs/guides/handle-failure.md): Make a workflow retry what is worth retrying, give up within a limit and clean up when a run ends badly, and see what each kind of failure looks like.
- [Start runs safely](https://realmengine.dev/docs/guides/idempotency-and-batches.md): Make a request that arrives twice start one run, not two. Also how to start a fresh run on purpose, and how to start many runs at once.
- [Test a workflow](https://realmengine.dev/docs/guides/test-a-workflow.md): Test a workflow's logic without a model, real services or a person: small files that say how a run should end, run by one command locally and in CI.
- [Operate runs](https://realmengine.dev/docs/guides/operate-runs.md): For the person who looks after runs: find the runs that need attention, get each kind moving again or end it, and keep the store tidy.
- [Deploy a project](https://realmengine.dev/docs/guides/deploy.md): Turn workflows that run on your machine into a project that runs on a server: the settings file, secrets, your own code, and a Realm server kept running.
- [Let an assistant plan its own workflow](https://realmengine.dev/docs/guides/agent-created-workflows.md): How an assistant connected to Realm writes a workflow for a task that none of yours covers, what Realm checks and refuses, and how it differs from a file.
- [Upgrade Realm](https://realmengine.dev/docs/guides/upgrade.md): Upgrade Realm without surprises: read what changed, upgrade every Realm package together, and check your workflows and runs against the new version.

## Reference: workflow file

- [Workflow file: top-level fields](https://realmengine.dev/docs/reference/workflow/top-level-fields.md): Every field that can appear at the top level of workflow.yaml, with its type, whether it is required, what it does, and an example that was run.
- [Workflow file: step fields](https://realmengine.dev/docs/reference/workflow/step-fields.md): Every field a step can have in workflow.yaml: which step kinds can use it, its type and default, what it does, and one example that uses them all.
- [Input maps, template expressions and filters](https://realmengine.dev/docs/reference/workflow/input-map-and-templates.md): How a workflow file refers to values that exist only during a run: input_map and template expressions, where values come from, and every filter.
- [Conditions: when, preconditions, abort_unless](https://realmengine.dev/docs/reference/workflow/conditions.md): How conditions are written for when, preconditions and abort_unless: the operators, how values of different kinds compare, and where the three fields differ.
- [Gates: trust and the gate block](https://realmengine.dev/docs/reference/workflow/gates.md): Reference for trust and the gate block: the trust values, every gate key, the rules the loader applies, and what is stored when a gate opens.
- [Retry and timeouts](https://realmengine.dev/docs/reference/workflow/retry-and-timeouts.md): How long a step may take and how often it is tried again: timeout_seconds, the keys of the retry block, and how they combine, with measured delays.
- [Agent-step controls](https://realmengine.dev/docs/reference/workflow/agent-step-controls.md): The settings that limit a model on an agent step: how many wrong answers are allowed, schema enforcement by the provider, request time and tool calls.
- [Services, tool servers, step templates, profiles and workflow context](https://realmengine.dev/docs/reference/workflow/services-profiles-and-context.md): Reference for services, mcp_servers, templates, agent profiles, workflow_context, context_wrapper and protocol: their keys, rules and when files are read.
- [Webhook trigger](https://realmengine.dev/docs/reference/workflow/webhook-trigger.md): Reference for the trigger block that lets an HTTP request start a run: every key, the ways a request can be checked, and the reply to each kind.
- [JSON Schema blocks](https://realmengine.dev/docs/reference/workflow/json-schema-blocks.md): The JSON Schema fields of workflow.yaml: what each is checked against, which parts of JSON Schema Realm accepts, and what the loader refuses or warns about.
- [What the loader refuses and warns about](https://realmengine.dev/docs/reference/workflow/loader-diagnostics.md): What realm workflow validate reports when it reads a workflow.yaml: accepted, accepted with warnings, or refused. Every warning code and the JSON output.

## Reference: command line

- [realm workflow](https://realmengine.dev/docs/reference/cli/realm-workflow.md): Reference for the realm workflow subcommands, which work on workflow files and registered workflows: their arguments, flags, output and exit codes.
- [realm run: commands that read](https://realmengine.dev/docs/reference/cli/realm-run-reading.md): Reference for the realm run subcommands that only read (list, inspect, attempts, diff, replay and export): their flags, output and exit codes.
- [realm run: commands that act](https://realmengine.dev/docs/reference/cli/realm-run-acting.md): Reference for the realm run subcommands that change a run or the store: their arguments, flags, output and exit codes.
- [realm agent](https://realmengine.dev/docs/reference/cli/realm-agent.md): Reference for realm agent, which drives one run from the command line with a model doing the agent steps: its flags, its output and its exit codes.
- [realm listen](https://realmengine.dev/docs/reference/cli/realm-listen.md): Reference for realm listen, the web server that starts a run for each accepted HTTP request: its flags, its startup, every line it logs, and how it stops.
- [realm mcp and realm serve](https://realmengine.dev/docs/reference/cli/realm-mcp-and-serve.md): Reference for realm mcp and realm serve, the two ways to start Realm's MCP server: their flags, what each prints, and how each refuses a request.

## Reference: MCP

- [MCP tools](https://realmengine.dev/docs/reference/mcp/tools.md): The tools of Realm's MCP server, which an AI assistant calls to find a workflow, start a run, do its steps and read its state, with parameters and replies.
- [Run state and health findings](https://realmengine.dev/docs/reference/mcp/run-state-and-health.md): Every field of the get_run_state reply, every value of next_actions_status, and the health findings that realm run inspect and the stuck-run list also report.

## Reference: code and settings

- [Adapters](https://realmengine.dev/docs/reference/adapters.md): The adapters Realm ships, with each one's settings and operations, and for each operation its parameters and the HTTP request it sends.
- [Handlers](https://realmengine.dev/docs/reference/handlers.md): Reference for handlers: the interface, what execute receives, what each return value and thrown error does, registration, and the helper functions.
- [Deployment manifest (realm.yaml)](https://realmengine.dev/docs/reference/deployment-manifest.md): Reference for realm.yaml, a project's settings file: its top-level keys and their rules, where Realm looks for the file, and what a run records about it.
- [Project extensions](https://realmengine.dev/docs/reference/project-extensions.md): How a project gives Realm its own adapters, handlers and processors: what each file must export, every refusal, when the code loads, and what a run records.
- [Testing package](https://realmengine.dev/docs/reference/testing-package.md): Reference for @sensigo/realm-testing, the package for testing workflows, handlers, adapters and stores: every value and type it exports.
- [Core library: stores and the store contract](https://realmengine.dev/docs/reference/core-library.md): Use @sensigo/realm as a library: the functions that run a workflow, the stores Realm ships, the store interfaces, and how to check a store of your own.

## Reference: lookups

- [Error codes](https://realmengine.dev/docs/reference/error-codes.md): Every error code Realm defines: when each one is raised and what it tells the caller to do, and the codes that nothing raises.
- [Run record and export bundle format](https://realmengine.dev/docs/reference/run-record-and-export.md): Every field of a run record and of an evidence entry, the objects inside them, and the fields of the file that realm run export writes.
- [Environment variables and files on disk](https://realmengine.dev/docs/reference/environment-and-files.md): Every environment variable Realm reads, and every file and folder it reads or writes, both under ~/.realm and in a project.
- [Glossary](https://realmengine.dev/docs/reference/glossary.md): The words these docs use with a meaning of their own, each explained in one or two sentences with a link to the page that covers it.

## Optional

- [How it works](https://realmengine.dev/how-it-works/): How a Realm run passes between the engine, an MCP client, realm agent and realm listen — four diagrams.
- [How Realm compares](https://realmengine.dev/compare.md): How Realm compares with other tools for multi-step AI agent work, question by question. Every answer cites the tool's own code or docs. The page itself is https://realmengine.dev/compare/.
- [Source code](https://github.com/sensigo-hq/realm): The Realm repository on GitHub, with the changelog and the docs as written.