MELRA
io.github.XAGI-LabPublished by GitHub account XAGI-Labv0.3.0-alpha.14Updated Oct 24, 2026
Local MCP runtime for policy-governed, verified agent actions with durable receipts.
Overview
Local MCP runtime that governs an agent's tool calls: policy checks, approvals, evidence verification, and durable receipts for routed actions.
- What you can do
- Plan, execute, inspect, cancel and judge bounded operations such as file writes, terminal commands, browser actions, HTTP requests and computer control
- Read durable task state and retrieve redacted evidence with an execution certificate
- Plan, advance, pause, resume, cancel and inspect restart-safe multi-step workflows
- Discover available operations, platform support, limits and policy posture
- Optionally expose ordinary tool names such as read_file, write_file and run_command that run through the same pipeline
- When to use it
- Worth adding when an agent makes changes on your machine or over the network and you want each routed action checked against a policy, approved before it runs, verified against declared evidence, and recorded in an auditable receipt. It suits teams that want governance, idempotency and crash recovery to outlive a single agent harness.
- Requirements
- Runs locally over stdio via npx from the @melra/cli package; Node.js 22.13+ or 23.4+ (or a container or prebuilt release). Setup writes a policy file and the MCP client's own config, and the chosen project directory becomes the workspace boundary; MELRA_WORKSPACE can override it. No API keys or headers are declared.
Installation
In SourceWeft
- Open MELRA in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
MELRA
Modular Execution Layer for Reliable Autonomy
Your AI agent decides what to do. MELRA governs how tool calls are authorized, verified, and recovered.
An open-source local execution runtime for agent tool calls you route through MELRA. It checks each call against policy, requests approval when needed, verifies declared evidence, and keeps a redacted receipt of what runs to an outcome. For each task, MELRA dispatches mutations at most once; uncertain outcomes are parked for reconciliation instead of replay. Exactly-once external effects still depend on the provider. Calls made through other tools remain outside MELRA's control.
[CI status] [CodeQL status] [Dependency audit status] [Container build status]
[Latest release] [@melra/cli on npm] [MELRA on the official MCP Registry] [Indexed on TensorBlock MCP Index] [Listed on mcpservers.org] [Listed on mcp.site] [MELRA on Smithery] [AGPL-3.0-only license, SDKs Apache-2.0] [55 of 55 deterministic evaluation scenarios passing] [Telemetry off]
[macOS] [Linux] [Windows] [Node.js 22.13 or newer, or 23.4 or newer] [Python 3.11 to 3.14] [Hardened Docker image]Works with [Claude Code] [Claude Desktop] [OpenAI Codex] [Cursor] [VS Code] [Gemini CLI] [Zed] [Windsurf] [OpenClaw] [Hermes Agent] [GitHub Copilot CLI] [and any MCP client]
26-second demo · Quick start · How it works · See what it is doing · Docs · Contribute · Discussions · Product Hunt launch
[MELRA governed execution flow]
26-second demo
https://github.com/user-attachments/assets/e5cf895d-7ea6-4797-a1ef-e69cc5860d3f
[!WARNING] MELRA is alpha software. The local runtime is tested end to end, but APIs may change before
1.0. Use an isolated workspace, keep domain and command allowlists narrow, and read every approval before you give it.
Quick start
You need Node.js 22.13 or newer, or 23.4 or newer. From the project the agent should work in, one command sets everything up:
That directory becomes the agent's workspace, the boundary for its file and command
operations. setup shows it, and asks before making your home directory, a directory
holding it, or / the workspace; set MELRA_WORKSPACE to choose another.
In a terminal, setup is a short wizard. It writes a safe local policy, finds the
agent apps on your machine, asks which one should use MELRA, and writes MELRA into
that app's own config file, keeping everything else in it (and saving a .bak first):
Then restart your agent app (Claude Code asks you to approve a project's server once) and ask it to do something, for example "use melra to show me the system info". That's it.
Prefer flags, a container, or building from source?
Every command prints readable output in a terminal and plain JSON when piped or with
--json, so scripts keep working. MELRA creates <MELRA_HOME>/payload.key with
private permissions on first start; back it up with the SQLite files, because losing
it makes persisted payloads unreadable. See installation for
every install path, environment variable, and the hardened Docker invocation.
[!CAUTION] This project publishes only under the
@melra/npm scope (@melra/cliis the CLI) and on its releases, where the Python SDK's wheel is. An unscoped npm packagemelraor a PyPI packagemelrais not this project's. Install from that scope, from this repository, or from the releases.
If MELRA helps, star the repository so other
agent builders can find it. Trying it in Cursor or another client? Share the client
and its version, your OS, and your MELRA version (npx @melra/cli@alpha version) in
issue #184; partial test results are
useful too.
What is MELRA?
AI agents no longer just talk. They edit files, run commands, click through websites and call APIs on your behalf. Four questions come with that, and most agents answer them differently, or not at all:
MELRA answers those questions in one place for tool calls routed through it, across supported agents. It sits underneath your agent for those calls, the way an operating system sits underneath your apps:
The LLM reasons. The harness manages the loop. MELRA governs the effect lifecycle for calls routed through it. Swap the model or the agent; MELRA's policies, approvals, credentials, history and receipts can stay in place.
Works with your agent
MELRA speaks the Model Context Protocol, so any MCP
client can use it. For these, melra setup --client <name> writes the config in the
client's own format and location, and melra doctor tells you whether each one is
pointed at MELRA:
Tested says how far each one has been taken: run in CI (an automated suite drives it), connected by hand (its own CLI connected to a packed release over MCP, but no task was run from inside it; see COMPATIBILITY.md), config checked against docs (the file and format come from its documentation or source, and the CLI tests write and read them back), or documented only.
Building your own agent? Use the TypeScript SDK or the
Python SDK. Both can spawn MELRA or connect to one that is already running
over loopback HTTP or a private Unix socket. For agent frameworks, see the
framework examples: the official MCP SDKs',
LangChain / LangGraph, OpenAI Agents SDK and Vercel AI SDK snippets all run in CI
with no model, as far as listing MELRA's tools and calling melra_capabilities.
[!NOTE] A named client is marked verified only after the released package, not a source checkout, passes discovery, planning, approval, execution, cancellation and receipt retrieval in that client. Per-client status lives in COMPATIBILITY.md.
How it works
An effect is one bounded operation an agent routes through MELRA: file.write,
terminal.run, browser.click, http.request, and so on. MELRA handles each routed
effect in nine stages, split between a plan step and an execute step (for a single
task, melra_plan then melra_execute) so that nothing runs at planning time:
Here is one change from start to finish, in developer mode. In
enforced mode the challenge carries no
phrase: you approve with melra approve <task-id> outside the conversation,
and the agent's melra_execute sends no approval at all.
What the final status means, and what an agent should do next:
Show the request an agent actually sends
The agent resolves "run the checks" into one bounded operation, plus the evidence that would prove it worked:
The task reaches verified_success only if the process exits 0. A process that runs
and exits 1 completed the action but failed the evidence, so it is reported as
partial. MELRA never receives a goal like "fix the production server": that needs
judgement, which belongs to the model. A kernel that interpreted sentences would be a
kernel whose guarantees depended on a model.
When an agent connects, MELRA also sends it a short guide to this loop (the MCP
server's instructions), so a model knows to declare evidence, read the status, and
never blindly retry an unknown outcome, without anyone prompt-engineering it.
See what it is doing
You can see each action MELRA handled and its policy decision, and, for each that ran to an outcome, its evidence and receipt, from the terminal or the browser. Nothing here can approve or start work, and approval phrases are never displayed.
Safe by default
What actually guards an effect depends on the mode:
melra doctor says which of these hold on its protection line, and
melra_capabilities reports approvals and sandbox beside mode.
Unsafe-local mode and the two deployment modes
Every row above can be switched off at once with melra serve --unsafe-local (or
MELRA_UNHINGED=1): no policy, no approvals, no evidence requirement, no workspace
confinement, no destination checks. The agent gets the reach your OS user has, apart
from a few fixed file checks that hold in every mode.
The mode announces itself on stderr, in melra doctor and in melra_capabilities,
and receipts still record what ran. See
unsafe-local mode.
The honest gap in a default install is that MELRA governs the effects it is asked
for. An agent holding both a MELRA terminal and a native one makes the kernel
optional. MELRA_MODE is where you say which situation you are in:
MELRA cannot verify that assertion from inside its own process, and it does not
pretend to; the isolation is the operating system's job. What enforced mode does is
close every door MELRA owns: --unsafe-local is refused outright, nothing binds
outside loopback (a 0600 Unix socket is allowed), no client can register itself,
every command MELRA runs gets an OS sandbox of its own that keeps it out of MELRA's
data and your logins (MELRA will not start where none works, unless the policy file
records the opt-out), and mode is stamped on every receipt. For the operating-system side,
examples/deploy has a hardened Docker run, a systemd
unit and a Compose pair that puts the agent in a container of its own, each checked
in CI, melra doctor reports which restrictions are actually in
effect, and melra probe, run inside the
agent's box, checks that it stops a workspace write, a read of MELRA's data, outbound
and local connections, and starting a shell. See
deployment modes,
the threat model and the security policy.
For Claude Code, melra launch claude-code takes the other path away for the
session it starts: Read, Glob and Grep are its only built-in tools and melra its
only MCP server, so the only tools it has that change anything are MELRA's. In
developer mode the agent approves its own changes, and a command MELRA runs for
it has your rights wherever no sandbox
works, so --mode enforced is how you decide each one. The
server it starts leaves node, npm, npx and pnpm out of the default
allowlist, unless the policy file lists them, as one melra setup wrote does:
remove the ones the agent does not need. A claude started any other way is
unchanged. See
launching an agent.
For OpenClaw and Hermes Agent,
melra setup --client openclaw --exclusive --write (or --client hermes)
turns the agent's own shell, web and file-changing tools off (Hermes's file
reads too) in its own config, through the switch each one documents, and
melra doctor says whether its exec or terminal is still enabled. That is
a default the agent's OS user can edit, not a boundary. See
OpenClaw's and Hermes Agent's tools.
Why MELRA
An LLM decides what to do. A harness runs the loop that gets it there. Something still has to decide whether the resulting effect is allowed, avoid replaying uncertain mutations, prove what happened, and survive a crash in the middle. Today that machinery is rebuilt inside every agent harness, and it dies with the harness. MELRA is that machinery, factored out and made agent-independent.
Next to the two layers it is most often mistaken for:
Plenty of MCP servers can do these things; this is not a claim that none of them do.
The difference is that in MELRA they are the execution contract rather than a per-tool
option. The boundary is partly shipped: MELRA_MODE=enforced closes every door
MELRA owns, but the OS isolation that stops a harness reaching the filesystem around
the kernel is the operator's to build; runnable hardened deployment recipes are still
to come (#52).
The feature test. Anything that would still make sense if the request came from ordinary deterministic software belongs in MELRA: authorisation, idempotency, credential isolation, recovery, verification, effect history. Prompt optimisation, LLM memory, model selection, a planner and agent personality belong to the harness above. That is why nothing in MELRA's execution path ever calls a model.
What it can do
Effect adapters
The kernel is the contract; these are its shipped implementations. Every one passes through the same policy, approval, budget, verification, receipt and certificate pipeline; an adapter that skipped it would not be an adapter.
Database, cloud and SaaS adapters are designed and on the roadmap, not shipped today. Semantic memory about the user (preferences, conversation history) belongs to the harness, not here.
A deliberately small tool surface
Twelve tools in front of the adapters and one durable workflow controller. The CLI, both SDKs, loopback HTTP and the Unix socket reach the same twelve operations; this list is the kernel contract, not an MCP-specific API.
A verdict records its judge as declared, and the certificate carries it beside
executedBy, the receipt's declared principal. Over MCP even
a human: judge is the harness's claim; only a cli: judge, from melra judge, came
through an operator surface.
Prefer tool names your model already knows? Set MELRA_HARNESS_TOOLS=1 and thirteen
more appear alongside these (read_file, write_file, run_command, browser_click,
approve, …). They are not a second path: each one builds an ordinary task and runs
the same pipeline. See ordinary tool names.
Durable, restart-safe workflows
Workflows compose operation, approval, condition, parallel, bounded_loop,
checkpoint, compensation, human_input and delegation nodes, and every effect
still travels through the task pipeline. Each CLI call below is a new process, so this
exercises restart persistence with no daemon:
Stop the process after any line and the next command resumes from the same
MELRA_HOME. Interrupted reads may retry; interrupted changes are never silently
repeated. They are settled by re-observation, or they park in recovery_required.
workflow advance and resume exit 0 while the run is fine, 3 while it waits on an
approval, 4 while it waits on an --input, and 2 once it has failed, ended
partially_complete or cancelled, or needs recovery. workflow plan, pause and
suspend exit 0 when they plan or halt the run; pausing or suspending a run that is
complete, cancelled or failed is refused. workflow inspect exits 0 in any state.
workflow cancel exits 0 when it leaves the run cancelled and 1 when it does not,
as for a run already complete. Errors exit 1.
Evidence and benchmarks
Numbers come from committed scripts and JSON artifacts, with dataset hashes and claim boundaries. They are component measurements, not a claim that MELRA is "the best" or that unlike benchmarks are comparable.
Raw artifacts: core microbenchmarks, LoCoMo and GovBench.
The repository also contains a pre-registered browser-agent harness (MiniWoB-125 and the WebArena-Verified Hard-30 registered subset) whose task IDs, upstream revisions and dataset hashes are frozen. Its score is not yet claimed: it will be published only after a full fixed-denominator run passes the publication gate. MELRA has not run an official OSWorld, WebArena or LongMemEval submission.
Reproduce the scores
The MiniWoB suite also needs the pinned MiniWoB++ assets and an agent configuration; see the research index and the methodology. Run outputs (HAR, screenshots, video, transcripts) are git-ignored and must never be committed.
For developers
Repository map
MELRA is capability-driven, not language-restricted: Rust, Go, Swift, C# or another language can be added when measurement shows a real benefit and the same conformance suite passes.
Runnable examples cover a read-only system task, a verified file write, a terminal check, browser inspection, scoped memory, computer capability discovery, a governed API call, independent verification, and a restart-safe workflow.
Documentation
Contributing
Code, adapters, client integrations, benchmark harnesses, verifier predicates, documentation and threat analysis are all welcome.
- Read CONTRIBUTING.md and the Code of Conduct.
- Sign your commits under the DCO (
git commit -s), and sign the CLA once, on your first pull request. - Run
pnpm checkbefore opening a pull request; it also checks links, the environment-variable table and the CHANGELOG shape. - Report vulnerabilities through private vulnerability reporting, never in a public issue.
License
The MELRA kernel, CLI and documentation are licensed under the
GNU Affero General Public License v3.0 only, and XAGI Labs Private
Limited also offers the kernel under a commercial license. The SDKs
(@melra/sdk, @melra/protocol and the melra Python package), the examples
and the code samples in the documentation stay under the
Apache License 2.0, so code that only calls MELRA can
use any license. Releases up to and including 0.3.0-alpha.22 were Apache-2.0
and stay so. LICENSING.md maps each path to its license and
explains what the AGPL asks of a modified MELRA run as a network service.
The MELRA name and logo are covered by TRADEMARKS.md; the official logo and hero artwork are all rights reserved. Third-party benchmark datasets keep their own licenses and are not included in this repository.
Built in the open by XAGI Labs.
MELRA brand assets © XAGI Labs Private Limited, all rights reserved.
Source: README.md at commit bacf5e3
Tools
0Version history
1- v0.3.0-alpha.14LatestOct 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts