Director

Appearance

Local dev ​

Two patterns, both supported.

Pattern 1 — pnpm dev against an existing Host ​

Cheapest. Assumes a Host is already running (e.g., hivecast install --home /tmp/matrix-home && hivecast start --home /tmp/matrix-home).

bash
cd projects/matrix-3/packages/director
MATRIX_DAEMON_ORIGIN=http://127.0.0.1:3100 pnpm dev

Vite serves Director out of src/ with HMR. The dev server proxies the gateway routes at MATRIX_DAEMON_ORIGIN (vite.config.ts:46-55):

/.matrix    → host gateway
/api        → host gateway
/auth       → host gateway
/login      → host gateway
/logout     → host gateway
/healthz    → host gateway
/nats-ws    → host gateway (WebSocket upgrade)

That means everything except Director's own assets and HMR pipe traverses the proxy to the running Host. The bootstrap response, NATS-WS connection, and any browser-driven RequestReply.execute calls all hit the real gateway.

Open http://localhost:5173/ (Vite default) and Director loads. Authentication, runtime tree, ops feed all use the live Host's actors.

Pattern 2 — mx run (run-in-place) ​

The package ships a .matrix/dev.environment.json so it can serve itself with a package-local runtime side, useful for proving Director against the package's own runtime without a shared Host.

bash
cd projects/matrix-3/packages/director
pnpm build
mx run . --env dev                                   # runtime-side services
MATRIX_DAEMON_ORIGIN=http://127.0.0.1:4332 pnpm dev  # browser side, with proxy

The runtime side is whatever the dev environment file declares. The browser side proxies to the runtime-side HTTP port (4332 in the example).

This is the standalone browser-package dev-server path. It does not require a shared deploy-local host. See RUN-IN-PLACE.md in the package root.

Pattern 3 — worker-container two-runtime topology ​

For full HiveCast-style dev (platform shell + edge shell), use the two-runtime recipe documented in CLAUDE.md:

bash
hivecast install --home /tmp/matrix-home --no-start
hivecast start --home /tmp/matrix-home --no-default-runtimes

matrix up @open-matrix/director --serve --port 5002 \
  --runtime-id DIRECTOR --env hivecast --startup auto --restart always

Director will be served at http://127.0.0.1:5002/apps/director/ behind the gateway.

Env vars Director respects ​

VariablePurpose
MATRIX_DAEMON_ORIGINWhere Vite proxies gateway paths in dev. Default http://127.0.0.1:3100.
NODE_ENVStandard Vite/Node env classifier.

Director itself does not read environment variables at runtime — it gets all configuration through the bootstrap response from the gateway.

Hot reload caveats ​

  • HMR works for Director's own components.
  • <matrix-dsl-host> does not survive HMR cleanly because it owns the NATS connection. After editing host-related code, refresh the page.
  • The chat-component surface is loaded lazily; if you edit it, you may need to clear the import cache in the browser DevTools.

See also ​

Source: projects/matrix-3/packages/director/RUN-IN-PLACE.md, vite.config.ts:43-57.