Start here

Two ways in you can take right now, and one worth knowing about. Pick the one that sounds like you — you can always come back for the others.

I use an AI assistant

Put limits on what it can do — 60 seconds, no code, no account.

I build agents

Your first agent in 5 minutes, with limits built in from day one.

I want it on my own machine

soon

One binary. Your agents, your documents, your hardware — nothing leaves it.

60 seconds · no code

Protect the assistant you already use

If your AI assistant (Claude Desktop, Cursor, Windsurf…) is connected to tools — GitHub, your files, a database — those tools will do whatever the AI asks. This adds a safety layer: some actions blocked, some ask you first, everything logged.

1

Open your assistant's tool config file

It's a small settings file listing the tools your assistant can use. Claude Desktop: claude_desktop_config.json · Cursor: ~/.cursor/mcp.json ·all clients →

2

Wrap a tool with the guard

Take any entry in that file and put the guard in front of it. Before and after:

// before                                  // after
"github": {                                "github": {
  "command": "npx",                          "command": "npx",
  "args": ["-y",                             "args": ["-y", "@aroha-sdk/mcp-guard",
    "@modelcontextprotocol/server-github"]     "--block", "delete_*",
}                                              "--gate",  "merge_*",
                                               "--",
                                               "npx", "-y", "@modelcontextprotocol/server-github"]
                                           }

Plain English: anything starting with delete can never happen. Anything starting with merge asks you first. Everything else works exactly as before.

3

Restart your assistant and test it

Ask it to delete something. It will tell you the action was blocked by policy — and a log of every decision lands in ~/.aroha/mcp-guard.jsonl. That's it. You're done.

Want budgets (“at most 10 of these per session”), recipes, and the full rule reference? mcp-guard docs →
5 minutes · TypeScript or Python

Build your first agent

An agent here is just a function behind an HTTP endpoint — with one superpower available when you want it: callers can hand it a signed permission slip (a mandate) that it physically cannot exceed.

1

Serve a function

import { serve } from "@aroha-sdk/run";   // npm i @aroha-sdk/run

const agent = serve("hello", async ({ message }) => `You said: ${message}`);
agent.start(8000);

Python is the same shape: pip install aroha, decorate a function with @serve.

2

Call it

curl -X POST http://localhost:8000/v1/run \
  -H "Content-Type: application/json" \
  -d '{"message": "hello there"}'

Streaming, sessions, and a health check are already wired. That's a complete agent.

3

Give it a limit it can't break

When your agent starts doing things that matter — spending, sending, deleting — you stop trusting instructions and start issuing signed permission slips. This one says “research only, at most 20 searches”:

import { issueTaskMandate } from "@aroha-sdk/credentials";

const { token } = await issueTaskMandate(
  myDid, agentDid,
  ["research", "web-search"],              // the only things it may do
  { actionLimits: { "web-search": 20 } },  // and no more than this
  myPrivateKey,
);

The 21st search doesn't fail politely — it's refused by signature verification, no matter what the model wants.

Next steps when you're ready: see where this fits in your agent's anatomy · deploy & register on the Hub · connect agents into webs · runnable examples
built and running · binaries not published yet

Run the whole thing on your own hardware

The other two paths add limits to software running somewhere else. This one moves the software. Your agents, their keys, your documents and the audit log all live on your machine, answering from a model you already run — nothing leaves it unless you send something.

1

One command, no infrastructure

aroha up

It finds a model you already run, gives each agent its own identity and keys, and serves a full interface on 127.0.0.1 — nothing is exposed to the network unless you ask for it. There is a desktop window too, for when you would rather not keep a terminal open.

2

The same guard rules, in a config file

Path A wraps one tool at a time from your assistant's config. Here the rules live once, in ~/.aroha/config.toml, and apply to every MCP server the runtime talks to:

mcpBlock = "delete_*, drop_*"
mcpGate  = "send_email"
mcpLimit = "create_*:10"

Servers can be a local subprocess or a remote HTTPS endpoint from the marketplace. Remote ones are trusted less on purpose — a tool Aroha cannot vouch for asks you once before its arguments are sent to somebody else's machine.

3

What you can do today

Everything above is implemented and running, but there are no published binaries yet, so there is nothing to download. The SDK in path B is the same protocol and is on npm and PyPI now — start there, and the runtime will read the agents you have already built.

The detail — desktop app, MCP marketplace, and why a remote server is trusted less than a local one: local runtime docs → · overview

Evaluating the protocol?

The full depth is here and it isn't simplified: formal spec, five-layer architecture, threat model, conformance suite, and the research behind the design.

Protocol spec →ArchitectureSpec repo (MIT)Benchmarks