Skip to content
Back to search

moira

Agent Workflow Engine for AI agents over MCP — per-step directives, completion conditions, and JSON-Schema validation. Self-hostable (Apache-2.0).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/moira-mcp/moira with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/moira-mcp/moira'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/moira-mcp--moira/badge.svg)](/listings/moira-mcp--moira)

HTML

<a href="/listings/moira-mcp--moira"><img src="/api/listings/moira-mcp--moira/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Self-Host (recommended)

Run a complete Moira instance locally with Docker — no source build required:

cp .env.example .env       # defaults work locally; review host, port, and artifact domain for another host
docker compose up -d

Then open:

- **Web UI**: http://localhost:8080 - **Documentation**: http://localhost:8080/docs/ - **MCP endpoint**: http://localhost:8080/mcp

The image is pulled from the public registry by default. Data (SQLite + execution storage) persists in `./data`. See [Self-Hosting](#self-host-recommended) or the in-app docs at `/docs/` for the full reference.

Updating / Upgrading

Update a normal self-host installation with the standard Compose commands:

docker compose pull
docker compose up -d
docker compose ps

Older `.env` files may still override Compose with the removed `0.3.5` tag; change that line once to `MOIRA_IMAGE=ghcr.io/moira-mcp/moira:latest` before updating.

The image protects existing self-host data before its startup migrations: it creates and verifies a coherent SQLite backup, includes the prompt manifest, and keeps three rotating recovery states under `data/.moira-startup-backups/`. If initialization fails, it restores the database and manifest before refusing to start the services. A persistent pending marker also restores the verified state before the next attempt if the container or host was interrupted mid-initialization. A fresh installation skips the nonexistent-database backup and uses only a temporary persistent marker so an interrupted first start is removed before retry.

The complete automatic recovery behavior and optional pinned-image preflight are documented in [Self-hosting: Updating and Recovery](packages/docs/src/content/docs/docs/getting-started/self-hosting.mdx#updating-and-recovery), with a matching [Russian version](packages/docs/src/content/docs/ru/docs/getting-started/self-hosting.mdx#обновление-и-восстановление). Release notes are on the [GitHub Releases](https://github.com/moira-mcp/moira/releases) page.

Local Development (from source)

For contributors who want to build and run from the source tree, switch `docker-compose.yml` to **Option B** first — comment out the `image:` line and uncomment the `build:` block (the file documents both options inline). Then:

nvm use
npm install
docker compose up -d --build   # builds the image locally from config/Dockerfile
# Web UI: http://localhost:8080  |  MCP: http://localhost:8080/mcp

(The default `docker-compose.yml` uses the prebuilt public image — `docker compose up -d` without `--build` — which is the recommended self-host path.)

Extensions (optional)

Custom node and communication-channel bundles run in the separate extension runner and are disabled by default. Enabling them requires this source checkout because the runner image is built locally; the published Moira image does not import or package bundle code.

mkdir -p extensions
cp -R examples/extensions/webhook-notify extensions/
printf '\nMOIRA_EXTENSION_RUNNER_URL=http://moira-extension-runner:9110\n' >> .env
docker compose --profile extensions up -d --build

Before starting the example, replace both placeholder network permissions and fill its per-user settings. The example contributes both a workflow action node and an ordinary notification channel. See [Self-hosting: Enable extensions](packages/docs/src/content/docs/docs/getting-started/self-hosting.mdx#enable-extensions) and [Writing an Extension](packages/docs/src/content/docs/docs/guides/writing-extensions.mdx) for the complete installation, SDK, permission and failure contracts. `npm run test:docker-extensions` verifies the default-off profile and read-only bundle mount.

Local codespaces on your computer

Moira Local connects your computer to your Moira account through outbound HTTPS. It runs approved repositories in persistent, mountless Docker Sandboxes microVMs. GitHub Codespaces remains a separate

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 142 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Moira
  2. Moira is a workflow engine for AI agents. An agent connects through the Model Context Protocol
  3. (MCP), receives the current instruction and completion criteria, performs the work, and submits a
  4. schema-checked response. Moira persists execution state so another agent session can continue the
  5. same run. The Web UI provides workflow editing, run inspection and account administration.
  6. Schema validation checks a response's structure; it does not prove that the work happened.
  7. Run the open-source application on your own infrastructure, or use the managed service at
  8. [moira-mcp.com](https://moira-mcp.com). This repository contains the engine, MCP server, Web API/UI,
  9. documentation and self-host deployment. See [the documentation index](docs/README.md) and
  10. [project structure](PROJECT-STRUCTURE.md) for source ownership.
  11. ## Self-host
  12. Install Docker with the Compose plugin. Use this checkout, or download the three deployment files
  13. following the [Self-Hosting guide](packages/mcp-server/src/help/content/getting-started/self-hosting.md#quick-start):
  14. `docker-compose.yml`, `.env.example` and `config/traefik-self-host.yml`. Keep the ingress configuration
  15. beside the Compose file.
  16. ```bash
  17. cp .env.example .env
  18. docker compose up -d
  19. ```
  20. The localhost defaults pull the public image without a source build. Open:
  21. - Web UI: <http://localhost:8080>
  22. - Documentation: <http://localhost:8080/docs/> (English) or <http://localhost:8080/ru/docs/> (Russian)
  23. - MCP endpoint: <http://localhost:8080/mcp>
  24. For another host, set `MOIRA_HOST`, `MOIRA_PORT` and `STATIC_ARTIFACTS_DOMAIN` together in `.env`.
  25. Published HTML artifacts use individual subdomains of the artifact domain; public deployments need
  26. the matching DNS and wildcard TLS. Preserve the supplied workspace Upgrade route through ingress;
  27. an ordinary frontend-port mapping is not equivalent. Configure proxy trust for your actual topology.
  28. See [deployment configuration](docs/operator/configuration.md) for origins, secrets, email and network admission.
  29. Self-host registration requires administrator approval. On first start the image generates missing
  30. secrets and prints the generated administrator password once; the default administrator email is
  31. `admin@moira.local`. Preserve `data/.secrets.env` with the database. Sign in, then approve new
  32. accounts through **Admin Panel → Users**. Self-host uses email/password; social login and broader
  33. cross-user administration/analytics follow the separate SaaS policy. See
  34. [account administration](docs/operator/accounts.md) for approval, blocking, password recovery and
  35. administrator access recovery, including installations without real email delivery.
  36. ## Connect an agent and use workflows
  37. Connect your MCP client to your instance's `/mcp` endpoint and complete its authenticated
  38. authorization flow. Use the [MCP Clients guide](packages/docs/src/content/docs/docs/integration/mcp-clients.mdx)
  39. for the configuration generated for each supported client. The connection name `moira-local` is a
  40. client label, independent of the optional Local companion executable.
  41. Ask the agent to discover available workflows and choose the current exact `owner/slug` for the
  42. task. The [workflow catalog](packages/docs/src/content/docs/docs/reference/workflows/index.mdx)
  43. explains the choices; the [Agent Guide](packages/mcp-server/src/help/content/integration/agent-guide.md)
  44. owns prepare/execute, step attempts, continuation and guarded cancellation. Runtime `help` discovers
  45. English topics; `help({ topic: "tools" })` renders the current typed tool catalog. The website also
  46. provides Russian translations.
  47. Use [workflow authoring](packages/mcp-server/src/help/content/guides/workflow-creation.md) and the
  48. [workflow CLI](docs/reference/workflow-cli.md) to create or edit definitions. Node syntax, templates,
  49. tool schemas and examples stay in their canonical references rather than a second README catalog.
  50. For public HTML results, see [artifacts](packages/mcp-server/src/help/content/concepts/artifacts.md)
  51. for upload, ownership, quotas, expiry and browser isolation.
  52. ## Update and recover
  53. Use the image selection in your installation's `.env`, then:
  54. ```bash
  55. docker compose pull
  56. docker compose up -d
  57. docker compose ps
  58. ```
  59. Before startup migrations of an existing self-host database, the image verifies a coherent SQLite
  60. snapshot and the prompt-manifest state. It retains rotating recovery states and an interruption
  61. marker; failure attempts restoration and keeps services unavailable. A first start has a separate
  62. cleanup path because no previous database exists. These safeguards do not replace operator backups.
  63. If initialization fails, inspect `docker compose logs moira` and follow
  64. [Updating and Recovery](packages/mcp-server/src/help/content/getting-started/self-hosting.md#updating-and-recovery);
  65. do not bypass the guard or repeatedly restart an unchanged failure. A confirmed bundled-workflow
  66. conflict uses the [catalog reconciliation procedure](docs/reference/bundled-catalog.md#self-host-conflict-recovery).
  67. Application accounts, workflows and executions persist in `./data`. Workspace files, full command
  68. output, operation receipts and immutable publications remain with their workspace service or paired
  69. controller. Back up those private owner stores and disks separately; a database backup does not
  70. contain their file bytes. Preserve encryption keys, and collect original operations after uncertain
  71. outcomes before considering another mutation. See [workspace recovery](docs/reference/workspaces.md#recovery-and-collection)
  72. and [GitHub Releases](https://github.com/moira-mcp/moira/releases).
  73. ## Optional workspace and extension support
  74. The paired Local controller can provision the common workspace service in GitHub Codespaces and
  75. run approved repositories in Local microVMs. Controller enrollment does not require initializing
  76. a physical Local VM. Local VM execution requires the supported macOS Apple-silicon runtime and
  77. explicit owner grants; repository Git authority is separate from social login. From the checkout:
  78. ```bash
  79. npm ci
  80. npm run local:build
  81. npm run local -- --help
  82. ```
  83. Follow [workspace setup and custody](docs/reference/workspaces.md) for pairing, physical capability,
  84. permissions, installation and explicit maintenance. Staging a release does not replace the running
  85. owner; client exit does not stop its VMs. The common `moira-workspace` guest CLI owns commands, files,
  86. sessions and original results in both Local and GitHub guests. Lost replies require collecting the
  87. original operation, not replaying the command or creating a replacement environment.
  88. Extensions are disabled by default. The optional Compose profile builds a separate runner from this
  89. checkout; binary channels execute beside their source owner. Follow
  90. [Enable extensions](packages/mcp-server/src/help/content/getting-started/self-hosting.md#enable-extensions)
  91. and [Writing an Extension](packages/mcp-server/src/help/content/guides/writing-extensions.md) for bundle
  92. installation, permissions, user settings and failure boundaries.
  93. ## Contribute
  94. Read [CONTRIBUTING](CONTRIBUTING.md) for issue coordination, pull requests, DCO and release policy.
  95. Use Node.js 24 and the root npm workspace:
  96. ```bash
  97. nvm use
  98. npm ci
  99. ```
  100. [Contributor setup](docs/development/getting-started.md) explains the isolated development container,
  101. environment selection and native build commands. The [testing guide](tests/TESTING-GUIDE.md) owns
  102. suite selection and root npm entrypoints; [the coverage map](tests/COVERAGE-MAP.md) locates maintained
  103. fixtures. Do not use the disposable contributor container for persistent installation data.
  104. Start at [docs/README.md](docs/README.md) for architecture, execution, HTTP/authentication,
  105. workspaces, UI patterns, documentation ownership, observability and operator procedures. Custom
  106. Claude Code commands are documented in [commands/README.md](commands/README.md). Current work is
  107. tracked in [GitHub Issues](https://github.com/moira-mcp/moira/issues).
  108. ## License, security and branding
  109. Source code is licensed under [Apache-2.0](LICENSE). See [third-party notices](THIRD_PARTY_LICENSES),
  110. [the trademark policy](TRADEMARK.md) for name/logo use, [the code of conduct](CODE_OF_CONDUCT.md),
  111. and [SECURITY.md](SECURITY.md) for vulnerability reporting. Private deployment branding, secrets and
  112. operational material belong outside this public repository.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.