hivecast-admin
Repositories Projects Packages Public Activity Starred Repositories

@open-matrix/daemon (0.3.4)

Published 2026-04-04 22:57:39 +00:00 by hivecast-admin

Installation

@open-matrix:registry=
npm install @open-matrix/daemon@0.3.4
"@open-matrix/daemon": "0.3.4"

About this package

@matrix/daemon

Matrix daemon — embedded NATS server, actor hosting, federation, FlowPad UI, and CLI tools. One install, batteries included.

Install

npm install -g @matrix/daemon

Quick Start

# Start the daemon (runs in background)
matrixd start --background --federation --realm MY-REALM

# Open FlowPad UI in your browser
#   http://localhost:3100/apps/flowpad/

# Query actors from the terminal
matrix -r MY-REALM introspect daemon
matrix -r MY-REALM send daemon ping
matrix -r MY-REALM catalog

# Load a project directory
matrixd start --background --federation --realm MY-REALM --dir ./my-project

Two CLIs

matrixd — Daemon Lifecycle

Command Description
matrixd start Start the daemon (NATS server + HTTP server + actors)
matrixd stop Stop the daemon
matrixd status Show daemon status (running/stopped, PID, realm)
matrixd config Show configuration
matrixd add <dir> Register a project directory
matrixd list List registered projects
matrixd remove <mount> Unregister a project

Start Options

matrixd start [options]
  -d, --dir <path>       Project directory to auto-load
  -p, --port <number>    NATS server port (default: 4222)
  -f, --federation       Enable federation via NATS leaf nodes
  -b, --background       Run daemon in background (detached)
  -v, --verbose          Enable verbose logging
  --realm <name>         Realm name (default: derived from directory)
  --max-depth <n>        Max directory scan depth (default: 3)
  --src-only             Only scan src/ folder

matrix — Actor Commands

Command Description
matrix introspect <path> Get actor type, status, accepts, emits
matrix send <path> <cmd> [payload] Send command, wait for reply
matrix ls <path> List children at path
matrix subscribe <path> [event] Stream events (Ctrl+C to stop)
matrix catalog List all actors in the daemon
matrix project add <path> Register project at runtime

Global Options

matrix [options] <command>
  -r, --realm <name>     Realm name (default: "matrix-3")
  -h, --host <host>      NATS server host (default: "127.0.0.1")
  -p, --port <port>      NATS server port (default: 4222)
  -t, --timeout <ms>     Timeout (default: 5000)
  --json                 JSON output

Examples

Introspect an actor

$ matrix -r MY-REALM introspect daemon
{
  "type": "DaemonActor",
  "mount": "daemon",
  "realm": "MY-REALM",
  "status": "running",
  "accepts": ["$introspect", "$catalog", "$config", "ping", "status",
              "scan", "listDir", "readFile", "loadProject", ...],
  "emits": ["pong", "statusResponse"]
}

Send a command

$ matrix -r MY-REALM send daemon ping
{ "message": "pong -> pong from daemon", "mount": "daemon" }

$ matrix -r MY-REALM send daemon scan
{ "projects": [...], "realm": "MY-REALM" }

Read a file from a project

$ matrix -r MY-REALM send 05-daemon-watcher.index_html read
{ "content": "<!DOCTYPE html>...", "path": "index.html", "size": 1234 }

List all actors

$ matrix -r MY-REALM catalog
Realm: MY-REALM
Components: 15

daemon          DaemonActor       examples=0
tree-domain     _TreeDomain       examples=0
05-daemon-watcher  FolderProjection  examples=0
...

Subscribe to events

$ matrix -r MY-REALM subscribe daemon *
Subscribing to daemon/$events (all events)...
Press Ctrl+C to exit.

[pong] {"message":"pong from daemon"}
[statusResponse] {"status":"running","uptime":42}

FlowPad UI

When the daemon is running, FlowPad is available at:

http://localhost:3100/apps/flowpad/

FlowPad provides:

  • Interactive query editor (JavaScript flow DSL + LISP)
  • Rich result viewers (trees, tables, data)
  • Built-in project categories with examples
  • Real-time transport message log
  • Federation backbone status

Federation

With --federation, the daemon connects to a NATS routing hub via leaf node, enabling cross-realm communication. Any FlowPad browser tab can query your daemon from anywhere.

# Start with federation
matrixd start --federation --realm ACME-PROD

# From another machine's FlowPad, query:
#   Target: ACME-PROD/daemon
#   Action: introspect

What's Included

Component Description
NATS Server Embedded NATS on port 4222
HTTP Server Static file server on port 3100
DaemonActor Root actor with introspect, catalog, scan, file I/O
FolderProjection Filesystem-to-actor mapping
TreeDomain Hierarchical state tree
Federation NATS leaf node federation
FlowPad Pre-built web UI
matrixd CLI Daemon lifecycle management
matrix CLI Actor query and control

Ports

Port Protocol Purpose
4222 NATS Local server (actors + CLI)
3100 HTTP FlowPad UI + health endpoint

Requirements

  • Node.js >= 20

License

MIT

Dependencies

Dependencies

ID Version
@mariozechner/pi-ai ^0.52.7
better-sqlite3 ^11.0.0
chokidar ^4.0.3
node-llama-cpp ^3.14.2
sqlite-vec ^0.1.6-alpha.2
typescript ^5.7.0
ws ^8.18.0

Development Dependencies

ID Version
esbuild ^0.27.3

Keywords

matrix actors nats federation flowpad daemon cli
Details
npm
2026-04-04 22:57:39 +00:00
2
Project Site
MIT
1.6 MiB
Assets (1)
daemon-0.3.4.tgz 1.6 MiB
Versions (9) View all
0.3.9 2026-04-05
0.3.8 2026-04-05
0.3.7 2026-04-05
0.3.6 2026-04-05
0.3.5 2026-04-05