Soma

One protocol for agents to trust each other, remember together, and pay for what they do.

A message between agents is an envelope, not a chat line. The envelope carries the goal, the task, a hard token budget, a mandate, a price, a deadline and a signature. Memory, transport, money and history are just carriers of that envelope.

POST /v1/messages
{"goal": "verify the artifact", "task": "run the linter", "to": "verifier",
 "token_budget": 2000, "mandate": {"max_cost_usd": 0.5}, "price_usdc": 0.005}

• Budget travels with the message. The receiver knows the limit before it starts.

• Refusals come with a reason. Every decline names the rule that fired.

• Degradation is declared. If context did not fit, the report says what was dropped.

• Signatures verify offline. Ed25519, public key included — no service, no secret.

• Cost is measured, not listed. Tokens, CPU, bytes, writes, external calls.

60 seconds

pip install -e ".[dev]"
soma keygen                       # ключ подписи Ed25519
soma serve                        # хаб на http://127.0.0.1:8765
soma send --to research --goal "find the market" --task "scan 3 sources" --budget 2000
soma inbox --agent research

Or in Python:

from mitra import Envelope, Hub

hub = Hub()
env = Envelope(goal="verify the artifact", task="run the linter", to="verifier",
               token_budget=2000)
hub.send(env)                       # подписан и поставлен в очередь
hub.inbox("verifier")               # что ждёт агента
hub.claim(env.id, "verifier")       # забрать (атомарно)
hub.complete(env.id, {"text": "ok"})

Related MCP server: DOS Kernel

Why

Agents already work. What they lack is a shared nervous system: each remembers only its own session, trusts on faith, spends without a mandate, and cannot prove what it did. Memory, provenance, authorization and accounting all exist — but as separate products that do not talk to each other.

Soma is the glue. It is deliberately small: the core is a protocol, a reference implementation and a conformance suite. Not a platform, not a framework, not a vendor.

What is in the box

Build your own hub, prove it speaks Mitra

The conformance suite is the point of this project. Point it at your implementation:

MITRA_CONFORMANCE_IMPL="my_package.hub:MyHubFactory" pytest tests/test_conformance.py -v

A factory receives a temp directory and must return an object with send, inbox, claim, complete, route, verify, stats. Twelve checks: signature verifies, tampering breaks it, budget is respected, degradation is declared, expired envelopes are not delivered, claims are exclusive, refusals explain themselves, completion closes the envelope, budget + mandate travel with the envelope, a mandate refusal names a rule, and a repeated envelope id does not overwrite the original.

Composing with what already exists

Soma does not replace any of these — it carries envelopes between them:

• MCP — an adapter exposes the same operations as MCP tools.

• A2A — agents.json in this repo is an A2A Agent Card; envelopes map onto A2A tasks.

• x402 — the payment header contract is defined in src/mitra/payments.py.

• OPA / Cedar — the mandate interface is a plain function; policy engines plug in.

• Sigstore / EIP-712 — same primitive (signed payload, public key travels with it).

• Arweave / IPFS / Nostr — the anchor interface is a seam; local hash chain works offline.

What is open and what is not

This is the whole point of the split, so it is written down plainly.

The reference implementations in this repository are deliberately minimal: enough to run, test and understand. They are not the engines. Our commercial bundle (Mitra Core) plugs into the same seams and is the best implementation of them we have — and it is not in this repository.

If you are reading this to decide whether to build on Soma: yes, build on it. If you are reading this to decide whether to use our hosted version instead of running your own: that is a fair question, and the answer depends on whether you want guarantees, the shared history and the managed key handling, or you would rather run everything yourself.

Plugging your own engine

The five seams are protocols (soma/interfaces.py): Signer, MandateEvaluator, MemoryTier, Meter, Anchor. A plugin is any object that satisfies them.

# my_engine.py
from soma.envelope import Mandate

class StrictMandate:
    name = "my-engine"

    def check(self, action, mandate, only=None):
        if action.get("payee") == "mallory":
            return False, "payee: blocked by my engine"
        return True, "ok"

def components():
    return {"mandate": StrictMandate()}

Load it two ways:

# 1) environment — for experiments and local runs
SOMA_PLUGINS="my_engine:components" soma serve

# 2) entry point — for a distributed package
#    [project.entry-points."soma.plugins"]
#    my_engine = "my_engine:components"
pip install my-engine && soma serve

GET /healthz reports what is actually connected:

{"components": {"signer": "ed25519", "mandate": "my-engine", "meter": "usage",
                "memory": "Memory", "anchor": "LocalChain", "plugins": ["my-engine"]}}

A broken plugin is skipped, not fatal: the hub starts with the reference implementations and says so in /healthz.

Who is who, and why it matters

The registry is a file. An agent joins it by proving it holds its key: the hub issues a one-time nonce, the agent signs it, and a foreign key cannot get in. When work is done, the executor signs a receipt; the hub verifies it and counts. Actions refused by a mandate are counted as breaches. Reputation is then a derived fact — verified_receipts − 4 × breaches — that anyone can recompute from the receipts, with no opinion and no stars.

Two nodes, one protocol

Nodes can share work and history. The default is private: an envelope leaves the node only if it is explicitly marked shared or public, and every envelope that arrives is signed and checked against the receiver's registry. History is a hash-linked chain that another node can import and verify — so it outlives the node that lived it. No blockchain is required for any of this; an external anchor (Arweave, IPFS) can publish the chain when you want one.

Server profile

By default the reference transport is local: no authentication, binds 127.0.0.1 — a component to put behind your own gateway. For a public deployment there is a managed profile:

SOMA_MANAGED=1 SOMA_TOKEN=<secret> SOMA_QUOTA_PER_HOUR=100 soma serve

Without a token configured, the managed profile is closed — a misconfiguration must not open the door. The quota is counted per sender, so one noisy agent cannot spend another's budget.

Trust, stated plainly

• The reference HTTP transport has no authentication and binds 127.0.0.1. Put it behind your own gateway (TLS, auth, rate limiting) before exposing it. Bodies are capped at 1 MiB.

• A signature proves integrity by itself. It proves origin only when the sender's public key is in the agent registry — otherwise anyone can sign their own envelope with their own key. The reference implementation checks the registry when it has one.

• The local history chain proves ordering and continuity; the newest entry needs an external anchor to be final.

Status

Beta. The protocol is versioned (soma/1); envelopes are signed, budgets are hard, refusals are explained. See ROADMAP.md for what is next and SECURITY.md for the trust model.

License

MIT.