@open-matrix/daemon

v0.1.1

Published

6 days ago

Matrix daemon — local MQTT broker, actor hosting, federation, FlowPad UI, CLI. One install, batteries included.

Downloads

177

0High
0Medium
0Low

open-matrix

matrix actors mqtt federation flowpad daemon cli

@matrix/daemon

Matrix daemon — local MQTT broker, 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 (MQTT broker + 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>    MQTT broker port (default: 1883)
  -f, --federation       Enable federation bridge to HiveMQ
  -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>      Broker host (default: "127.0.0.1")
  -p, --port <port>      Broker port (default: 1883)
  -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 public MQTT backbone (HiveMQ) 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 | |-----------|-------------| | MQTT Broker | Local Aedes broker on port 1883 | | 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 | HiveMQ backbone bridge | | FlowPad | Pre-built web UI | | matrixd CLI | Daemon lifecycle management | | matrix CLI | Actor query and control |

Ports

| Port | Protocol | Purpose | |------|----------|---------| | 1883 | MQTT | Local broker (actors + CLI) | | 3100 | HTTP | FlowPad UI + health endpoint |

Requirements

Node.js >= 20

License

MIT