npm package: @open-matrix/daemon
Description: Matrix daemon — local MQTT broker, actor hosting, federation, FlowPad UI, CLI. One install, batteries included.
Latest version: 0.3.1

# @matrix/daemon

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

## Install

```bash
npm install -g @matrix/daemon
```

## Quick Start

```bash
# 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

```bash
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

```bash
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

```bash
$ 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

```bash
$ 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

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

### List all actors

```bash
$ 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

```bash
$ 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.

```bash
# 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