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.
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
Markdown
[](/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
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.
- # 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](https://moira-mcp.com). This repository contains the engine, MCP server, Web API/UI,
- documentation and self-host deployment. See [the documentation index](docs/README.md) and
- [project structure](PROJECT-STRUCTURE.md) 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](packages/mcp-server/src/help/content/getting-started/self-hosting.md#quick-start):
- `docker-compose.yml`, `.env.example` and `config/traefik-self-host.yml`. Keep the ingress configuration
- beside the Compose file.
- ```bash
- 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](docs/operator/configuration.md) 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](docs/operator/accounts.md) 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](packages/docs/src/content/docs/docs/integration/mcp-clients.mdx)
- 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](packages/docs/src/content/docs/docs/reference/workflows/index.mdx)
- explains the choices; the [Agent Guide](packages/mcp-server/src/help/content/integration/agent-guide.md)
- 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](packages/mcp-server/src/help/content/guides/workflow-creation.md) and the
- [workflow CLI](docs/reference/workflow-cli.md) 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](packages/mcp-server/src/help/content/concepts/artifacts.md)
- for upload, ownership, quotas, expiry and browser isolation.
- ## Update and recover
- Use the image selection in your installation's `.env`, then:
- ```bash
- 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](packages/mcp-server/src/help/content/getting-started/self-hosting.md#updating-and-recovery);
- do not bypass the guard or repeatedly restart an unchanged failure. A confirmed bundled-workflow
- conflict uses the [catalog reconciliation procedure](docs/reference/bundled-catalog.md#self-host-conflict-recovery).
- 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](docs/reference/workspaces.md#recovery-and-collection)
- and [GitHub Releases](https://github.com/moira-mcp/moira/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:
- ```bash
- npm ci
- npm run local:build
- npm run local -- --help
- ```
- Follow [workspace setup and custody](docs/reference/workspaces.md) 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](packages/mcp-server/src/help/content/getting-started/self-hosting.md#enable-extensions)
- and [Writing an Extension](packages/mcp-server/src/help/content/guides/writing-extensions.md) for bundle
- installation, permissions, user settings and failure boundaries.
- ## Contribute
- Read [CONTRIBUTING](CONTRIBUTING.md) for issue coordination, pull requests, DCO and release policy.
- Use Node.js 24 and the root npm workspace:
- ```bash
- nvm use
- npm ci
- ```
- [Contributor setup](docs/development/getting-started.md) explains the isolated development container,
- environment selection and native build commands. The [testing guide](tests/TESTING-GUIDE.md) owns
- suite selection and root npm entrypoints; [the coverage map](tests/COVERAGE-MAP.md) locates maintained
- fixtures. Do not use the disposable contributor container for persistent installation data.
- Start at [docs/README.md](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](commands/README.md). Current work is
- tracked in [GitHub Issues](https://github.com/moira-mcp/moira/issues).
- ## License, security and branding
- Source code is licensed under [Apache-2.0](LICENSE). See [third-party notices](THIRD_PARTY_LICENSES),
- [the trademark policy](TRADEMARK.md) for name/logo use, [the code of conduct](CODE_OF_CONDUCT.md),
- and [SECURITY.md](SECURITY.md) for vulnerability reporting. Private deployment branding, secrets and
- operational material belong outside this public repository.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.