Moira

MCP Moira

Moira is a workflow engine for AI agents. An agent connects through the Model Context Protocol (MCP), receives the current instruction and completion criteria, performs the work, and submits a schema-checked response. Moira persists execution state so another agent session can continue the same run. The Web UI provides workflow editing, run inspection and account administration. Schema validation checks a response's structure; it does not prove that the work happened.

Run the open-source application on your own infrastructure, or use the managed service at moira-mcp.com. This repository contains the engine, MCP server, Web API/UI, documentation and self-host deployment. See the documentation index and project structure for source ownership.

Self-host

Install Docker with the Compose plugin. Use this checkout, or download the three deployment files following the Self-Hosting guide: docker-compose.yml, .env.example and config/traefik-self-host.yml. Keep the ingress configuration beside the Compose file.

cp .env.example .env

docker compose up -d

The localhost defaults pull the public image without a source build. Open:

• Web UI: http://localhost:8080
• Documentation: http://localhost:8080/docs/ (English) or http://localhost:8080/ru/docs/ (Russian)
• MCP endpoint: http://localhost:8080/mcp

For another host, set MOIRA_HOST, MOIRA_PORT and STATIC_ARTIFACTS_DOMAIN together in .env. Published HTML artifacts use individual subdomains of the artifact domain; public deployments need the matching DNS and wildcard TLS. Preserve the supplied workspace Upgrade route through ingress; an ordinary frontend-port mapping is not equivalent. Configure proxy trust for your actual topology. See deployment configuration for origins, secrets, email and network admission.

Self-host registration requires administrator approval. On first start the image generates missing secrets and prints the generated administrator password once; the default administrator email is admin@moira.local. Preserve data/.secrets.env with the database. Sign in, then approve new accounts through Admin Panel → Users. Self-host uses email/password; social login and broader cross-user administration/analytics follow the separate SaaS policy. See account administration for approval, blocking, password recovery and administrator access recovery, including installations without real email delivery.

Connect an agent and use workflows

Connect your MCP client to your instance's /mcp endpoint and complete its authenticated authorization flow. Use the MCP Clients guide for the configuration generated for each supported client. The connection name moira-local is a client label, independent of the optional Local companion executable.

Ask the agent to discover available workflows and choose the current exact owner/slug for the task. The workflow catalog explains the choices; the Agent Guide owns prepare/execute, step attempts, continuation and guarded cancellation. Runtime help discovers English topics; help({ topic: "tools" }) renders the current typed tool catalog. The website also provides Russian translations.

Use workflow authoring and the workflow CLI to create or edit definitions. Node syntax, templates, tool schemas and examples stay in their canonical references rather than a second README catalog. For public HTML results, see artifacts for upload, ownership, quotas, expiry and browser isolation.

Update and recover

Use the image selection in your installation's .env, then:

docker compose pull

docker compose up -d docker compose ps

Before startup migrations of an existing self-host database, the image verifies a coherent SQLite snapshot and the prompt-manifest state. It retains rotating recovery states and an interruption marker; failure attempts restoration and keeps services unavailable. A first start has a separate cleanup path because no previous database exists. These safeguards do not replace operator backups. If initialization fails, inspect docker compose logs moira and follow Updating and Recovery; do not bypass the guard or repeatedly restart an unchanged failure. A confirmed bundled-workflow conflict uses the catalog reconciliation procedure.

Application accounts, workflows and executions persist in ./data. Workspace files, full command output, operation receipts and immutable publications remain with their workspace service or paired controller. Back up those private owner stores and disks separately; a database backup does not contain their file bytes. Preserve encryption keys, and collect original operations after uncertain outcomes before considering another mutation. See workspace recovery and GitHub Releases.

Optional workspace and extension support

The paired Local controller can provision the common workspace service in GitHub Codespaces and run approved repositories in Local microVMs. Controller enrollment does not require initializing a physical Local VM. Local VM execution requires the supported macOS Apple-silicon runtime and explicit owner grants; repository Git authority is separate from social login. From the checkout:

npm ci

npm run local:build npm run local -- --help

Follow workspace setup and custody for pairing, physical capability, permissions, installation and explicit maintenance. Staging a release does not replace the running owner; client exit does not stop its VMs. The common moira-workspace guest CLI owns commands, files, sessions and original results in both Local and GitHub guests. Lost replies require collecting the original operation, not replaying the command or creating a replacement environment.

Extensions are disabled by default. The optional Compose profile builds a separate runner from this checkout; binary channels execute beside their source owner. Follow Enable extensions and Writing an Extension for bundle installation, permissions, user settings and failure boundaries.

Contribute

Read CONTRIBUTING for issue coordination, pull requests, DCO and release policy. Use Node.js 24 and the root npm workspace:

nvm use

npm ci

Contributor setup explains the isolated development container, environment selection and native build commands. The testing guide owns suite selection and root npm entrypoints; the coverage map locates maintained fixtures. Do not use the disposable contributor container for persistent installation data.

Start at docs/README.md for architecture, execution, HTTP/authentication, workspaces, UI patterns, documentation ownership, observability and operator procedures. Custom Claude Code commands are documented in commands/README.md. Current work is tracked in GitHub Issues.

License, security and branding

Source code is licensed under Apache-2.0. See third-party notices, the trademark policy for name/logo use, the code of conduct, and SECURITY.md for vulnerability reporting. Private deployment branding, secrets and operational material belong outside this public repository.