pub enum Request {
Show 29 variants
RegisterService(RegisterServiceParams),
Status,
Invite(InviteParams),
Pair(PairParams),
PeerRemove(PeerRemoveParams),
PeerRename(PeerRenameParams),
PeerAdd(PeerAddParams),
OpenSession(OpenSessionParams),
RosterInstall(RosterInstallParams),
OrgJoin(OrgJoinParams),
SetRosterUrl(SetRosterUrlParams),
SetNickname(SetNicknameParams),
SetAppMetadata(SetAppMetadataParams),
SetRelays(SetRelaysParams),
UnregisterService(UnregisterServiceParams),
PeerServices(PeerServicesParams),
ServiceAllowGrant(ServiceAllowParams),
ServiceAllowRevoke(ServiceAllowParams),
BlobPublish(BlobPublishParams),
BlobGrant(BlobGrantParams),
BlobRevoke(BlobRevokeParams),
BlobUnpublish(BlobUnpublishParams),
BlobRepublish(BlobRepublishParams),
BlobList(BlobListParams),
BlobFetch(BlobFetchParams),
AuditSummary,
AuditPrune(AuditPruneParams),
AuditList(AuditListParams),
Subscribe,
}Expand description
Control-API requests. Serialized as { "method": "...", "params": {...} }
(JSON-RPC-shaped; the id/jsonrpc envelope is added by the transport layer).
Each param-carrying variant wraps its named *Params struct — the ONE wire truth for that
method’s params, shared by clients (which serialize whole Requests) and the daemon (which
deserializes params into the same struct after its method-string dispatch). Adjacent
tagging serializes a newtype variant’s content as the struct’s fields, so the wire shape is
identical to inline variant bodies.
Servers dispatch on the method string and deserialize params per-method — tolerating
omitted / null / empty-object params for parameterless methods — rather than deserializing a
whole message into Request (adjacent tagging rejects params:{} for unit variants).
This keeps the wire tolerant for third-party clients (the versioned, additive-only surface).
Use method_of to extract the tag, then match + deserialize params per-method.
Variants§
RegisterService(RegisterServiceParams)
Register/update a [services.*] entry idempotently.
Status
Invite(InviteParams)
Mint a one-time pairing invite granting services. The daemon
answers an InviteResult carrying the copyable mcpmesh-invite: line. Tag
"invite" (snake_case). method_of needs no per-variant arm — it reads the
method string generically; the tag comes from rename_all.
Pair(PairParams)
Redeem a pairing invite. The daemon dials the inviter named by
invite_line on mcpmesh/pair/1, proves the secret, writes the mutual
(dial-back) PeerEntry, and answers a PairResult. Tag "pair"
(snake_case); method_of reads the method string generically.
PeerEntry — the durable allowlist row — lives in the daemon crate.
PeerRemove(PeerRemoveParams)
Remove a paired peer by nickname (mcpmesh pair --remove). The daemon drops the
peer’s PeerEntry (identity) AND revokes its access by stripping its stable principals from every
[services.*].allow (authorization) — the inverse of the pairing grant. Idempotent: a
nickname with no entry / no allow membership is a clean no-op. Live in-flight sessions are
NOT severed here: existing sessions run to completion; the peer only loses the
ability to establish NEW authorized sessions. Tag "peer_remove" (snake_case);
method_of reads the method string generically (no per-variant arm).
PeerEntry — the durable allowlist row — lives in the daemon crate.
PeerRename(PeerRenameParams)
Rename a contact’s nickname (nickname) authoritatively. Renames the
PERSON — every PeerEntry sharing user_id when given (one op for all their devices), else the
single nickname entry (a provisional, no-user_id contact) — to to, AND rewrites the old
nickname → to in every [services.*].allow so grants follow the rename. Refuses (error frame)
when to is empty or already names/grants a DIFFERENT identity — the same collision guard the
pairing rendezvous uses, so a rename can’t inherit another peer’s access. Tag "peer_rename";
host-privileged like the other pair ops.
PeerAdd(PeerAddParams)
RESERVED / INTERNAL (docs/local-protocol.md “Reserved / internal methods”): install a
peer directly from a raw endpoint_id — the trust-population stand-in for pairing behind
mcpmesh internal peer add. A deliberate, documented exception to the surface discipline
(raw endpoint identifiers otherwise never cross this socket); NOT part of the stable
vocabulary — do not build on it. Tag "peer_add".
OpenSession(OpenSessionParams)
Open a mesh session to peer/service; the daemon dials and pipes.
Distinct from the proxy’s job: this returns a session the client streams.
Named open_session rather than connect to avoid colliding
with the connect porcelain.
RosterInstall(RosterInstallParams)
Install a signed roster from a local file (the manual internal roster install path).
path is a LOCAL file the same-uid daemon reads (the daemon runs as the caller’s own
uid, so passing a path rather than the bytes crosses no trust boundary). org_root_pk
pins the org root on FIRST install (b64u:); omit it
once pinned (config carries it). Tag "roster_install".
OrgJoin(OrgJoinParams)
Pin the org root on a JOINER — WITHOUT a roster (the joiner has none yet; its poll loop
fetches the first one). Records [identity] org_id / org_root_pk / user_id / user_key.
user_key is a LOCAL path
(the key never crosses the API). Tag "org_join".
SetRosterUrl(SetRosterUrlParams)
Pin the HTTPS roster URL ([roster].url) in config. Written by org create --roster-url (the operator keeps it current) AND by join when the org invite carries one —
so the joiner’s poll loop bootstraps its FIRST roster. The daemon writes it under
reload_lock (single-writer), then the poll loop picks it up on the next daemon start. Tag
"set_roster_url".
SetNickname(SetNicknameParams)
Rename this node LIVE (#37): validate + upsert [identity].nickname through the
daemon’s own serialized config-write path (no lost-update window against a
concurrent grant/registration) and update the in-memory name future invites
present — no restart. Ack result. Tag "set_nickname" (snake_case).
SetAppMetadata(SetAppMetadataParams)
Set this node’s opaque app-metadata blob (#39): validated (≤256B) and folded, signed,
into each outgoing presence heartbeat, so paired roster peers see it in their status
presence — no per-peer session. Ack result. Tag "set_app_metadata". In-memory (lost
on restart; the embedder re-sets on startup).
SetRelays(SetRelaysParams)
Set this node’s CUSTOM relay set LIVE (#53): validate each URL as an iroh RelayUrl, diff
against the running endpoint’s current custom relays and apply the delta via iroh 1.0.3
Endpoint::insert_relay/remove_relay (no endpoint rebuild, no dropped sessions), then
persist [network] relay_mode="custom" relay_urls=[…] under reload_lock. When the node
is currently default/disabled, the config is persisted but the live mode transition
isn’t possible — SetRelaysResult::restart_required is true. Answers a
SetRelaysResult. Tag "set_relays".
UnregisterService(UnregisterServiceParams)
Grant a single stable principal access to a single service’s allow (#44) — the per-peer
“sharing on” toggle, idempotent + serialized under the config lock. Ack result.
Remove a service registration (#50) — the deregistration mirror of register_service.
Removes the whole [services.<name>] entry (allow included) + any ephemeral one, then
hot-reloads. Idempotent. Ack result.
PeerServices(PeerServicesParams)
Discover which services a paired peer CURRENTLY grants the caller (#52) — dials the peer
and returns the service names whose allow admits the caller’s principal. Answers
PeerServicesResult.
ServiceAllowGrant(ServiceAllowParams)
ServiceAllowRevoke(ServiceAllowParams)
Revoke a single stable principal from a single service’s allow (#44) — “sharing off” WITHOUT unpairing (the peer’s identity row is untouched; only NEW sessions are refused). Idempotent. Ack result.
BlobPublish(BlobPublishParams)
Publish a LOCAL file INTO a scope: the daemon adds the bytes to its gated
app-blob store and records the hash in scope. path is a local file the same-uid daemon
reads. Answers a BlobPublishResult carrying the mcpmesh/blob/1 ticket + hash.
Tag "blob_publish".
BlobGrant(BlobGrantParams)
Grant a scope to a principal — any flat-namespace entry: a group name, a user_id, or a
nickname (the shared principal_set expansion). Tag
"blob_grant".
BlobRevoke(BlobRevokeParams)
Tag "blob_revoke": withdraw principals from ONE scope’s grants (#62).
BlobUnpublish(BlobUnpublishParams)
Tag "blob_unpublish": remove a hash from ONE scope (#62). Withdraws reachability, not
bytes.
BlobRepublish(BlobRepublishParams)
#83: make a blob this daemon already holds servable from HERE, in a scope it controls.
Answers a BlobPublishResult — same shape as blob_publish, so a client can treat the
two interchangeably after a fetch.
BlobList(BlobListParams)
List the daemon’s blob scopes (name → hashes + grants). Tag "blob_list".
BlobFetch(BlobFetchParams)
Fetch a mcpmesh/blob/1 ticket THROUGH the daemon (BLAKE3-verified streaming) and export the
verified blob to dest_path (a local file the same-uid daemon writes). Answers a
BlobFetchResult with the verified hash + byte length. Tag "blob_fetch".
AuditSummary
Summarize this node’s LOCAL audit log into per-peer / per-service SESSION counts
(local-only — the daemon reads its OWN audit dir, nothing is transmitted). The host Mesh surface
renders these as “who serves me / whom I serve / session counts”. Parameterless (like Status);
the server dispatches on the method string. Tag "audit_summary" (snake_case);
method_of reads the method string generically (no per-variant arm).
AuditPrune(AuditPruneParams)
Delete audit months strictly older than before (#88) — the retention lever the log
never had. Local-only and owner-only (the control socket is the daemon owner’s). Answers
AuditPruneResult. Tag "audit_prune".
AuditList(AuditListParams)
Read this node’s LOCAL audit records, filtered and paged (#88) — the “show me everything
you hold about me” verb. Local-only; nothing is transmitted. Answers
AuditListResult. Tag "audit_list".
Subscribe
Open a live event stream (pairing liveness & health telemetry). Like open_session, the
connection STOPS being request/response after this call and becomes a one-way push stream
of StreamFrames. Parameterless. Tag "subscribe".