Matrix Protocol

Motivation

Without a shared protocol, every actor, component, feed, and service in this stack would speak its own bespoke wire format and the substrate would degrade into a pile of disconnected products that cannot address, discover, or compose each other. Matrix exists to give all of them one typed bus contract: an addressing scheme, a message envelope, a registry, and a security model that any runtime can implement and any client can speak. These docs are for the people who design the wire — protocol authors, SDK implementers, runtime maintainers, and gateway integrators who need the substrate to behave the same way under every transport. End-users and product readers do not belong here; they want the per-product docs (Chat, Director, HiveCast). If you are looking for "how do I send a message in the chat app," close this tab and read the product docs instead.

What this is and why

Matrix is docker-for-actors / npm-for-actors. Same shape as Docker and npm, mapped onto a typed actor system: you publish a Package, a Runtime hosts it as a DeploymentInstance, and that instance's actors live at Mounts — typed addresses on a pub/sub/RPC bus. The bus is the substrate. Everything else (chat, director, the inference market, third-party Matrix pages) is a vertical built on top.

This package documents the substrate's protocol layer: the wire grammar, how actors declare what they do, how mounts are claimed and discovered, how identity and capabilities flow, and how the same actor address speaks NATS, HTTP, WebSocket, MCP, and the target REST/OpenAPI/gRPC/AsyncAPI gateways.

Source: the substrate framing comes from WORKSTREAMS/thesis/THESIS.md Part 1 ("What Matrix actually is") and Part 4 ("Why the architecture is what it is"). The docker-for-actors model is normatively specified in WORKSTREAMS/loose-ends/items/P1.40-docker-for-actors-multi-package-runtimes.md.

Where this fits

This is substrate documentation, not vertical documentation. Matrix-the-protocol is what you must understand before reading docs for any vertical (Chat, Director, FlowPad, Smithers, the inference market, third-party Matrix pages).

Layer	Owned by
Bus, addressing, actor contract, registry, catalog, security primitives	this package (docs-matrix)
Building actors, components, packages	docs-sdk
Operating Hosts, Runtimes, Devices	docs-runtime-host, docs-edge, docs-devices
Verticals (Chat, Director, etc.)	their per-package docs
The HiveCast product on top	docs-hivecast

The three primitive types every Matrix actor is one of — Feed, Service, Component — and the three execution tiers (Local Host, Hosted Host / future on-demand edge, External connectors like system.com / system.win32) are defined in the thesis. This package documents the bus contract those primitives live on.

Five-minute quickstart

Stand up a Host and inspect a live actor on the bus. From the repo root:

# 1. Install + start a Host into a fresh home (uses bundled NATS).
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs install --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs start   --home /tmp/matrix-home

# 2. Health.
curl -fsS http://127.0.0.1:3100/healthz | jq .

# 3. Ask the bus what's mounted (this is a *bus invocation*, not an HTTP query).
matrix invoke system.devices devices.list '{"includeOffline":true}'
matrix invoke system.registry registry.list '{}'

Expected output for registry.list is a JSON envelope listing live mount claims — chat, chat.conversation, system.runtimes, system.gateway.http, host.control, etc. — each with the runtime that currently owns the claim. On the wire, every one of those mounts is addressed as {root}.{mount}.$inbox for ops, {root}.{mount}.$events for pub/sub.

Note: matrix invoke ... is the canonical way to ask the substrate what is happening. There is no generic GET /api/registry, GET /api/devices, or GET /api/apps endpoint on a Matrix Host. Inventory queries are bus invocations; HTTP exists only at documented boundaries (browser bootstrap, OAuth, static assets, NATS WebSocket upgrade, healthz, webhooks, federation handshake). See P1.43 for the full closed list.

Conceptual map

Read these in order if you want the substrate model end-to-end. Skip ahead if you already know what a NATS subject looks like.

Section	What you get
Overview	The conceptual model: actors, subjects, mounts, sessions, request/reply, events. Start here if you have never seen Matrix.
Addressing	The wire grammar ({root}.{mount}.$facet), authority roots (Space ID vs Space path vs authority root), Host vs Runtime wire roots, mount claims, relative-vs-absolute.
Actor Invocation	The envelope shape every message uses, correlation IDs, timeouts, streaming sessions.
Registry and Catalog	system.registry (authority for live mount claims) vs system.catalog (read projection for capability queries). The three discovery surfaces (Catalog / Browse / Live).
Security Model	Capability tokens, principal identity from transport metadata, device grants, credentials by reference.
Protocol Adapters	NATS native plus HTTP, WebSocket, MCP, and the target REST/OpenAPI / gRPC / AsyncAPI gateways.
Reference	Subject naming reference, envelope schemas, error codes, reserved subjects, compatibility rules.

What this domain does NOT own

• Host installation, supervision, packaging, deploy operations — those live in docs-hivecast, docs-runtime-host, docs-package-lifecycle.
• Per-vertical CLIs (Chat, Director, FlowPad, Smithers) — their own docs packages.
• The HiveCast product (account management, billing, marketplace, Devices UX) — docs-hivecast and docs-platform.
• Implementation walkthroughs for individual system actors — covered by the platform reference; this domain documents only the protocol contract those actors satisfy.

Authoritative anchors

Concern	Authoritative source
Substrate framing (docker-for-actors, three tiers, three primitive types)	WORKSTREAMS/thesis/THESIS.md
Multi-package runtimes, isolation declarations, DeploymentInstance	P1.40
Single-source matrix.json manifest, per-component relativeMount	P1.41
DeploymentInstance registry (two-tier identity, naming modes)	P1.42
HTTP-API reduction (bus is authority)	P1.43
Wire format {root}.{mount}.$facet	CLAUDE.md Rule 11; projects/matrix-3/packages/core/src/transport/NatsTransport.ts:108, lines 257–413
Six static declarations on actors	ACTOR-COMMUNICATION-CONTRACT.md
Authority vs projection table	MATRIX-AUTHORITY-MODEL.md
Discovery vocabulary	MATRIX-DISCOVERY-METADATA-SPEC.md
MatrixActor base class	projects/matrix-3/packages/core/src/core/MatrixActor.ts
Runtime lifecycle	projects/matrix-3/packages/core/src/runtime/MatrixRuntime.ts

When this documentation diverges from the code, the code is what IS. Pages mark target-state behaviour with explicit > **Status: target state — ships in v0.5/v1.** callouts so navigation never lies about what the substrate does today.

Sister docs

• docs-sdk — building actors, components, and packages.
• docs-runtime-host — installing and operating a Matrix runtime host.
• docs-hivecast — the HiveCast product on top of the substrate.
• docs-omega — Omega Lisp, the in-loop scripting language for agents.