docs(maestro): describe the single-host architecture
ci / rust (push) Successful in 2m40s

Rewrites CLAUDE.md as the current-architecture reference, drops the
registry from INSTALL/PRODUCT/DESIGN and the web README, deletes the
registry Dockerfile, and marks the dated design specs superseded where
they describe the registry, JWT auth, or cross-host attach.

The installer loses its configure step — every config field now has a
default, so a daemon starts with no config file at all.
This commit is contained in:
Miguel Palhas
2026-08-22 10:26:49 +01:00
parent de097cf17f
commit c856333e4a
25 changed files with 156 additions and 326 deletions
+18 -24
View File
@@ -1,7 +1,7 @@
# maestro-web
Browser UI for Maestro. Connects to the registry HTTP/WS API for the catalog
and to individual daemons (via direct WebSocket) for terminal I/O.
Browser UI for Maestro. Talks to a single local daemon over its `/api/*`
HTTP/WS surface — session catalog, spawn/kill, and terminal I/O.
## Framework choice: vanilla TypeScript
@@ -11,17 +11,17 @@ rendering; everything else is a session tree and a spawn form, both trivial
in plain DOM.
This decision is non-architectural — swap in a framework later without
touching the registry or daemon if needed.
touching the daemon if needed.
## Layout
```
src/
main.ts # entry point, hash-route dispatch
api.ts # registry HTTP API client
api.ts # daemon HTTP API client
events.ts # `/api/events` WebSocket subscriber
catalog.ts # session tree view (groups by metadata.label)
attach.ts # xterm.js + daemon WS attach view
catalog.ts # session tree view (groups by working directory)
attach.ts # xterm.js + attach WS view
spawn.ts # spawn-session modal
theme.ts # dark/light theme toggle + persistence
types.ts # mirror of `maestro-protocol` JSON shapes
@@ -39,40 +39,34 @@ follows the OS by default and can be pinned via the header toggle (persisted in
`localStorage`).
`mock.ts` is a DEV-only fixture (stripped from production builds): visit the dev
server with `?mock` to seed a representative catalog without a running registry,
server with `?mock` to seed a representative catalog without a running daemon,
`?mock&spawn` to open the spawn modal, and `?theme=light|dark` to pin a theme.
Routing is hash-based:
- `#/` → catalog
- `#/attach/<session-id>` → terminal
This keeps the registry's static handler dumb (no SPA fallback needed).
Concurrent attaches: open the same `#/attach/<id>` URL in another tab.
This keeps the static handler dumb (no SPA fallback needed). Concurrent
attaches: open the same `#/attach/<id>` URL in another tab.
## Dev
```sh
pnpm install
pnpm dev # http://localhost:5173, proxies /api → http://127.0.0.1:8080
pnpm build # → dist/, embedded into the registry binary at cargo build time
pnpm dev # http://localhost:5173, proxies /api → http://127.0.0.1:7070
pnpm build # → dist/, embedded into the maestro-web binary at cargo build time
```
The Vite dev server proxies `/api` and the events WebSocket to a
`maestro-registry`. Default is `http://127.0.0.1:8080`; point it elsewhere by
exporting `MAESTRO_REGISTRY` before `pnpm dev`:
The Vite dev server proxies `/api` and the WebSockets to a local daemon.
Default is `http://127.0.0.1:7070`; point it elsewhere by exporting
`MAESTRO_DAEMON_URL` before `pnpm dev`:
```sh
MAESTRO_REGISTRY=https://maestro-registry.example.com pnpm dev
# Daemon-facing URL also works — `wss://...` is rewritten to `https://...`
# and a trailing `/daemon` is stripped.
MAESTRO_REGISTRY=wss://maestro-registry.example.com/daemon pnpm dev
MAESTRO_DAEMON_URL=http://laptop.lan:7070 pnpm dev
```
Direct daemon WS connections (for attach) bypass the proxy and use the URL
returned by `GET /api/sessions/:id/connect-info`.
## Production
`pnpm build` writes the bundle to `web/dist/`. The Rust registry crate
embeds that directory via `rust-embed` at compile time and serves it from
`/`. See `crates/maestro-registry/src/web_assets.rs`.
`pnpm build` writes the bundle to `web/dist/`. The `maestro-web` crate embeds
that directory at compile time and serves it from `/`, reverse-proxying `/api/*`
to the daemon. See `crates/maestro-web/src/static_bundle.rs`.