Matrix SDK

Matrix SDK is the package-author layer for building Matrix actors, browser surfaces, and broker-connected applications without depending on the HiveCast platform repo.

This repository contains the SDK packages that were split out of Matrix-3 and renamed to their publishable @open-matrix/* package names. The split is proven as a standalone workspace: a fresh clone can install, build, test, type-check, pack every package, and compile an external consumer against the packed tarballs.

What You Can Build

Headless actors with MatrixActor
Browser custom elements with MatrixActorHtmlElement
In-memory actor graphs for tests and local development
NATS-backed transports for broker-connected actors
Browser host integrations for Matrix web surfaces
Package-author CLIs and project scaffolds

Matrix SDK is provider-neutral. It does not require HiveCast, Device Link, Host Link, Host Service, or a local HiveCast install. HiveCast is one managed provider that can issue broker credentials and host runtimes on top of the SDK.

Packages

Package	Purpose
`@open-matrix/sdk`	Public umbrella facade for actor/package authors
`@open-matrix/core`	Actor kernel, runtime, transports, serialization, browser actor base classes
`@open-matrix/cli`	Package-author `matrix` CLI
`@open-matrix/browser-kit`	Browser app shims, theme tokens, Vite helpers, shell components
`@open-matrix/browser-host`	Browser runtime host shell and app-ready integration
`@open-matrix/contracts`	Shared type contracts for placement, service registry, and runtime presence
`@open-matrix/federation`	Cross-realm messaging, MX envelope handling, and routing helpers
`@open-matrix/omega-core`	Narrow Omega interpreter facade used by Matrix membranes

Prefer narrow imports when possible:

import { MatrixActor } from '@open-matrix/core';

Use the umbrella package when you intentionally want the public SDK facade:

import { MatrixActor } from '@open-matrix/sdk';

Quick Start

git clone git@github.com:matrix-sdk/matrix-sdk.git
cd matrix-sdk
pnpm install --frozen-lockfile
pnpm prove

pnpm prove runs the standalone proof:

clean -> build -> test -> type-check -> pack all packages

For the external-consumer proof:

pnpm prove:external-consumer

That proof packs the SDK packages, creates a temporary consumer outside this repo, installs the packed tarballs, compiles TypeScript, starts a MatrixActor, and calls it through the Matrix runtime/transport path.

Minimal Actor

import {
  InMemoryBroker,
  InMemoryTransport,
  MatrixActor,
  MatrixRuntime,
  TopicRouter,
} from '@open-matrix/core';

class EchoActor extends MatrixActor {
  static accepts = {
    echo: {},
  };

  onEcho(payload: { message?: string }) {
    return {
      ok: true,
      message: payload.message ?? null,
    };
  }
}

const broker = new InMemoryBroker();
const transport = new InMemoryTransport(broker, { name: 'demo' });
const runtime = new MatrixRuntime({ transport, logging: false });

await runtime.create(EchoActor, 'demo.echo');

const replyTo = '$replies.demo';
const response = new Promise((resolve) => {
  const unsubscribe = transport.subscribe(replyTo, (value) => {
    unsubscribe();
    resolve(value);
  });
});

transport.publish(TopicRouter.inbox('demo.echo'), {
  op: 'echo',
  payload: { message: 'hello' },
  replyTo,
  correlationId: 'demo-1',
});

console.log(await response);
await runtime.shutdown();

CLI

The SDK CLI package owns the package-author matrix binary.

matrix init [dir]
matrix add actor <name>
matrix actor <name>
matrix configure --key <key> --cloud <url> --space <space>
matrix run <entry> --mount <mount>
matrix invoke <mount> <op> [json]

The current CLI proof is:

pnpm prove:cli-uat

The CLI is intended to let a package author initialize a folder, add actors, configure broker access, run actors, and invoke them without importing HiveCast product packages into the SDK layer.

Repository Layout

packages/
  browser-host/
  browser-kit/
  cli/
  contracts/
  core/
  federation/
  omega-core/
  sdk/
scripts/
  prove-external-consumer.mjs
  prove-sdk-cli-uat.mjs

Current Status

Done and proven:

The SDK packages build independently from Matrix-3.
Package identities use final @open-matrix/* names.
@open-matrix/sdk re-exports the public actor facade.
A fresh clone passes pnpm install --frozen-lockfile && pnpm prove.
A temporary external consumer can install packed SDK tarballs, compile, start a MatrixActor, and call it through Matrix runtime/transport.

Still planned:

Provider-neutral credential resolution for matrix configure and SDK users.
matrix login --provider hivecast to write the same config shape as matrix configure.
Direct broker mode with explicit broker URL/JWT/seed credentials.
HiveCast provider mode where HiveCast issues scoped broker credentials.
Publishing the packages to npm after the provider-login contract is complete.

Relationship To HiveCast

Matrix SDK is the open, provider-neutral actor SDK.

HiveCast is a managed overlay on top of Matrix SDK. HiveCast can provide account management, Spaces, API keys, broker credential issuance, runtime hosting, package distribution, and operator UI. SDK users should still be able to connect to another broker directly when they already manage their own broker credentials.

5.4 KiB Raw Blame History