Director

What this is and why it exists

Matrix is docker-for-actors / npm-for-actors — a typed pub/sub/RPC substrate where every Feed, Service, and Component is an actor on a federated bus. Director is one vertical built on top of that substrate. It is the operator console: a Visual Studio-style explorer for the actors, mounts, runtimes, and packages that make up a running Matrix Host.

Pick an actor in the tree, see its declared interface (accepts, emits, streams), inspect its state, browse its memory and sessions, prompt it through the embedded Chat surface, watch operations cross the bus in the Ops Feed. Director is the surface a developer or operator opens when the question is "what is actually running, and what is it doing?".

Director is a pure browser Package (@open-matrix/director). It owns no headless services and no backend ops; every byte it renders comes from invoking read ops on bus actors that live in other packages.

Motivation

A substrate without an operator console is unobservable: actors run, mounts come and go, packages register, and nobody can see any of it without scraping log files. Director exists to be that live view — runtimes, mounts, packages, ops in flight — rendered from the same bus actors that power everything else. It is also the dashboard surface that the local Device shell and the cloud platform shell both embed, so the panes you learn here are the panes you will see whether you operate your own Host or somebody else's. Read these docs if you run a Matrix Host, debug an actor pipeline, or need to know in real time what the registry, runtimes, and devices currently look like.

Where this fits

• Vertical, not substrate. Director consumes the substrate's introspection contract; it does not define it. The contract itself (Actor Communication Contract, registry, catalog, runtime inventory) is documented in docs-matrix and docs-sdk.
• The dashboard surface IS Director. Both Matrix-Edge (the local Device shell) and Matrix-Web (the cloud platform shell) embed Director as their primary observability surface. Edge is not a "lite" version of a separate dashboard — Edge is structurally and functionally identical to the cloud shell at the auth/identity boundary, and both surface Director as the operator console (see P1.44).
• Tier 1 today, Tier 2 ready. Director runs in any browser pointed at any Host's gateway. It connects via same-origin WebSocket to the bus, like every other Matrix browser surface.

Five-minute quickstart

# Build director (and the Host wrapper if needed)
pnpm --filter @open-matrix/director build
pnpm --filter hivecast build

# Install + start a Host
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

# Open Director
#   http://127.0.0.1:3100/apps/director/

Behind every Director pane is a bus invocation. To verify the same data Director sees, query the same actors directly:

# What runtimes are registered (Director's tree top level)
matrix invoke system.runtimes runtimes.registered '{}'

# What logical mounts the substrate knows about (Director's tree branches)
matrix invoke system.registry registry.list '{}'

# The cross-cutting capability catalog (Director's catalog/search)
matrix invoke system.catalog catalog.list '{}'

# The Devices facade (rendered by Edge / matrix-web's Devices view)
matrix invoke system.devices devices.list '{"includeOffline":true}'

These are not HTTP endpoints. They are bus mounts (system.runtimes, system.registry, system.catalog, system.devices) addressed by their declared accepts ops over NATS subjects. Director uses the same calls; the only difference is the page renders the response.

Conceptual map

• Overview — what Director is and isn't, its boundary against Platform Admin (hivecast / mx-cli / host.control) and the Agent Platform (system.agents / system.inference), the runtime-topology lens.
• UI — runtime tree, actor detail tabs, package status, logs and traces, diagnostics — described from the rendered components.
• Integration — every system actor Director queries (system.runtimes, system.registry, system.catalog, system.bindings, system.devices, system.observability.*, system.agents), with the exact ops, payloads, and timeouts.
• Development — local dev loop, package boundaries, UI architecture (Pattern A page-actor + composed children), testing, plugin surfaces.
• Reference — registered routes/elements, ops accepted, troubleshooting.

Cross-references

• Substrate framing: WORKSTREAMS/thesis/THESIS.md, Part 1 (substrate) and Part 3 (the three discovery surfaces — Catalog / Browse / Live; Director is the Live surface).
• Bus is authority: P1.43. Director is the canonical example: every inventory query is a bus invocation, never GET /api/....
• Edge full parity: P1.44. Edge surfaces the same five registries (Devices / Runtimes / Packages / Mounts / App Routes) that Director surfaces; Edge is not a degraded shell.
• Multi-package runtime model Director itself will deploy under: P1.40, P1.42.
• Sister vertical packages: docs-chat, docs-flowpad, docs-smithers.

Status note: target-state operator surfaces. DESIGN.md describes a workstream cockpit and a structured operator-mutation surface (steering, persistent state, config, source code). Most of those ops do not exist on backend actors yet. Today Director ships Explorer Mode (actor tree + tabbed detail + Ops Feed + Workstreams shell + Search). Pages mark target-state material with explicit callouts; do not read DESIGN.md as shipped behavior.

Source: projects/matrix-3/packages/director/src/index.ts (custom-element registration), src/DirectorApp.ts (page actor and data flow), src/services/DirectorRuntimeAdapter.ts (the read-only bus adapter), matrix.json (manifest and route prefix).