Introduction to Moira

Moira keeps an AI agent on track with one clear step at a time, checking each result before it moves on so multi-step tasks finish completely and in order. A flow (workflow) defines the process once for repeatable execution.

You do not have to build flows

Moira is an agent-first tool. You work with your agent the way you always do: describe the task in plain words. The agent does the rest:

It picks a ready flow when one fits — for example Quick Task, Robust Task or Todo List for a clear task without special logic, or Software Development Flow for a change to a code repository.
Or it builds a new flow for your task through the Workflow Management Flow, Moira’s own flow for creating and editing flows. A flow can be as simple as a few steps in a row or as complex as a process with reviews and repair loops. The agent first agrees with you how thorough the flow should be: a simple one is built quickly and gets a light check, a larger one goes through design and independent review. A flow can always be made more thorough later.

Everything else — web diagrams, variables, node types and editing a flow by hand — is optional. Use it to look inside a flow when you want; you need not learn it first.

Finding your way in the web app

The web app explains itself on screen:

At first sign-in, home offers a tour. “Show me around” opens the guides menu, “Later” asks next session, and “No thanks” is remembered.
“Show me around” stays in the sidebar: full tour, current page’s tour, resume and progress per screen. The full tour goes in order — home, overview, flows, the example flow, runs, your latest run, notes, playbooks, artifacts and Settings. Leaving a page pauses it until you resume. With no run yet, its stop explains how to start one. Tutorials starts or resumes Build your first flow, hands-on in the flow editor.
“What is this?” runs the page’s tour. Its card explains a page element beside it or at a screen edge; on phones, at the top or bottom. Long text scrolls inside; Back, Next and Close stay visible. Right arrow or Enter advances, left arrow goes back, Escape closes. A dot marks new or changed steps in a tour you have seen; pressing the button shows only those steps.
Every app page has a tour: home, overview, the flow list and each flow, the runs list and each run, notes, playbooks, artifacts and Settings. Tours explain page purpose and main controls, skipping steps for panels you have hidden. The admin area has no tour.
Your stopping point and seen steps follow your account across browsers. Settings → Preferences → Guides restarts the full tour or forgets seen steps.

Administrator overview

Admin Panel shows health/flow reconciliation. Cloud analytics cards show active people/work, new accounts, attention, popular flows and run stats. Per-card period buttons use rolling windows or Today (UTC midnight); choices last on this page.

Excluded users defaults to admins: search name/email or Include everyone. Choices stay per account/browser, without sync. Refresh retains labelled scope; errors/retry stay local.

Activity is a recorded action or observed provider renewal of an unexpired session, not online status. No renewal is inferred from signup/old stamps. Last step is an accepted step; missing times are unknown.

Manage all users/runs/flows keeps all records and all-period account details. Exclusions leave management/health unchanged. Default self-host: health and Users, no analytics.

Admin Settings groups definitions/values/maintenance/Codespaces; ?tab=values selects a section. Updates/errors/retry stay local; other controls, loaded data and drafts remain.

Development environments

Use workspace_list({ provider: "local-sandboxes" }) or workspace_list({ provider: "github-codespaces" }) to find persistent environments for one provider. Pass the selected environment’s returned reference to command and file tools. Use workspace_targets with the same provider to select an approved repository and paired controller before creation. The normal list includes known incomplete setup; choose view: "diagnostics" for unavailable or uncertain identities and their original operations, or view: "history" for confirmed retired environments. Local discovery does not await GitHub or billing. Settings → Development: environments, GitHub connection and local computers. Approve pairing on your computer; its companion applies pending owner settings within local limits. Both providers run the same guest workspace service. MCP and the direct guest moira-workspace CLI share its commands, files and retained output; its owned Node runtime is independent of the project. Current owner permissions and physical resources remain enforced without command/file quotas. Setup, permissions and security.

A gradual path

Start at the top and stop wherever you have what you need:

Quick Start — connect Moira to your AI client and run a first flow.
Tutorial: your first flows — three tiny learning flows: plain steps, one choice, several paths. They show how Moira runs a flow, one idea at a time.
Which ready flow to use — Quick Task, Robust Task and Todo List for everyday tasks, and when to ask your agent for a new flow instead.
Concepts and Patterns — how flows are built, for when you want to read or shape one yourself.

What goes wrong without structure

On a long task, AI agents can:

Lose focus on complex multi-step tasks
Skip important steps or prerequisites
Produce inconsistent results
Miss quality checks and validation

A flow gives each step:

a directive — what to do;
a completion condition — when it counts as done;
an input schema — the evidence the agent must return (optional);
connections — where the process goes next, including a choice by the agent’s answer.

The agent executes each step, returns its evidence, and Moira validates it and moves to the next step of the flow.

How It Works

The rest of this page is for the curious, and for agents that execute flows.

flowchart LR
    A[Start Workflow] --> B[Execute Step]
    B --> C{Validate Completion}
    C -->|Success| D[Next Step]
    D --> B
    C -->|Workflow Complete| E[End]

Execution Flow

Agent starts a workflow via MCP tool
Receives current step directive and completion condition
Executes the directive
Returns result via step() tool
Engine validates and advances to next step
Repeat until workflow completes

The workflow state persists on the server. If a session is interrupted, the agent can resume from the exact same step using the process ID.

Key Concepts

Workflows

A workflow is a directed graph of nodes. Each node represents a step in the process. Nodes can branch conditionally, loop, or delegate to subgraphs.

{
  "id": "my-workflow",
  "metadata": {
    "name": "My Workflow",
    "version": "1.0.0",
    "description": "Example workflow"
  },
  "nodes": [
    { "id": "start", "type": "start", "connections": { "default": "task-1" } },
    {
      "id": "task-1",
      "type": "agent-directive",
      "directive": "...",
      "connections": { "success": "end" }
    },
    { "id": "end", "type": "end" }
  ]
}

Node Types

Common node types are shown below. This table is representative, not exhaustive; see Nodes for every supported type and its current contract.

Type	Purpose
`start`	Entry point for workflow execution
`end`	Terminal node marking completion
`agent-directive`	Task for agent with directive and completion condition
`condition`	Branch execution to one of several outputs by cases
`expression`	Compute values using arithmetic expressions
`subgraph`	Delegate to another workflow
`user-notification`	Notify through the current user’s configured channels

Templates

Templates allow dynamic content in directives and conditions using {{variable}} syntax:

{
  "directive": "Analyze {{projectName}} and create {{reportType}} report"
}

Variables can reference:

Initial data from start node
Results from previous steps
Workflow parameters

Executions

An execution is a running instance of a workflow. It maintains:

Current position - Which node is active
Context - Variables and step results
History - Completed steps and outcomes

MCP Integration

Moira connects to AI agents via Model Context Protocol. The MCP server provides tools for:

Tool	Purpose
`list`	Browse available workflows
`start`	Prepare or execute a workflow start
`step`	Execute current step and advance
`manage`	Create, edit, and retrieve workflows
`session`	Get user info and active executions

MCP is an open protocol. Moira works with any MCP-compatible client: Claude Code, Cursor, and others.

Self-host or Cloud

Moira is open source (Apache-2.0). The engine, node types, and MCP tools are identical whether you host it yourself or use the managed cloud:

Self-host

Run the engine, Web UI and MCP server with the supplied app-and-ingress Docker Compose on your own infrastructure — free, single-tenant, your data stays with you. Private-team accounts register behind administrator approval. This is the default (DEPLOYMENT_MODE=self-host). See the Self-hosting guide.

Moira Cloud

A managed instance with nothing to operate, at moira-mcp.com. Adds SaaS-only social login, legal-consent and email-verification policy, and the broader multi-user administration surface.

Self-host opens registration behind administrator approval. SaaS-only email verification, legal-consent, and social-login behavior remains off by default. See Self-hosting for the deployment-mode details.