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.