MELRA

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.

Works with

26-second demo · Quick start · How it works · See what it is doing · Docs · Contribute · Discussions · Product Hunt launch

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:

cd ~/project

npx @melra/cli@alpha setup

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):

Which MCP client should use MELRA?

1. Claude Code detected: 'claude' on PATH
2. Cursor detected: config file found
3. Gemini CLI detected: config folder found ...

Choose 1-26 [1]: 1 Write it into ~/project/.mcp.json? [Y/n]

✓ Workspace ~/project ✓ Policy ~/.melra/policy.json ✓ Claude Code ~/project/.mcp.json

Next: Start claude in this workspace and approve the 'melra' server when it asks; 'claude mcp list' then shows it connected. Or start it with 'melra launch claude-code', so MELRA's are the only tools it has that change anything.

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 /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/cli is the CLI)

and on its releases, where the Python

SDK's wheel is. An unscoped npm package melra or a PyPI package melra is

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:

🛡️ Is it allowed?

Every action MELRA receives is checked against your policy, and checked again at the moment it runs. Risky changes wait for your exact approval.

✅ Did it really work?

"No error" is not success. An action counts only when the evidence you declared holds: the file exists, the exit code is 0, the page says what it should. For a file change or a memory delete MELRA also checks the end state itself: a written file holds exactly the bytes sent.

🔁 What if it crashes?

Every mutation MELRA dispatches is recorded before it runs and runs at most once. After a crash, MELRA settles it from its evidence or the provider; what it cannot settle waits in recovery_required and is never replayed.

🧾 What happened?

Every action MELRA runs to an outcome leaves a redacted, append-only receipt and a certificate that carries its own digest, so you can audit what ran, who asked, and why it was allowed.

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:

<img src="docs/assets/read