Director — Overview

Director is the top-level visual control surface for the local Matrix runtime. It answers four questions for an operator or developer:

1. What runtimes are registered, and which actor mounts do they provide?
2. What does this actor look like — what ops does it accept, what state does it hold?
3. Has anything happened recently that involves this actor — what came in, what went out?
4. Can I prompt this actor directly, or send it an operator command, without leaving the page?

Today (2026-05-05) Director ships Explorer Mode: actor tree, tabbed detail (Overview, Interface, State, Cognitive, Memory, Children, Sessions, Chat), Ops Feed, Workstreams shell, and Search. The full Workstream Cockpit and structured operator-mutation surface described in DESIGN.md are target state — most of the relevant ops do not exist yet on backend actors.

Pages

• What is Director? — concise problem statement and what Director provides today.
• Director vs Platform Admin — boundary against host-control / system-gateway-http operations.
• Director vs Agent Platform — Director uses system.agents and the Agent Platform tooling; it does not own the agent runtime.
• Runtime topology view — how Director composes system.runtimes + system.registry into the displayed tree.
• Actor and control surfaces — present and target-state operator surfaces.

What Director is not

• Not a replacement for Chat. The Chat tab inside Director loads the embeddable conversation surface from @open-matrix/chat-component/surface as a lazy chunk (see DirectorChatSurfaceHost). For full Chat usage, run @open-matrix/chat.
• Not a host-control front-end. Director does not start, stop, install, or restart runtimes. Runtime lifecycle goes through host.control / system.runtimes ops via mx-cli or hivecast commands.
• Not a security-admin console. Identity, device linking, and authority assignment live in system-auth and the matrix-edge / matrix-web shells.

Where Director runs

Director is registered as a webapp in matrix.json:

"webapp": {
  "distDir": "dist",
  "entry": "index.html",
  "appName": "director",
  "displayName": "Director",
  "icon": "🧭",
  "navOrder": 20,
  "shells": ["platform", "edge"]
}

The Host's gateway serves it at /apps/director/ on both the platform shell (matrix-web / HiveCast Host) and the edge shell (matrix-edge). It boots inside <matrix-dsl-host bootstrap-mode="hosted" url-params> (see src/index.html), which means it expects the gateway's bootstrap response to populate the transport (NATS-over-WebSocket), authority root, and runtime target root.

Source: projects/matrix-3/packages/director/matrix.json, src/index.html, and src/index.ts (monitorMatrixAppReady block).