feat(maestro): serve the web UI from the daemon
The browser reached the daemon through maestro-web, a second binary that served the SPA and reverse-proxied /api/* — two TCP connections and a WebSocket frame re-encode on every keystroke and every byte of PTY output. On one machine that hop buys nothing. The daemon now embeds the bundle and serves it off its own listener, behind a default-on `web` feature. `--no-default-features` builds without pnpm or node; MAESTRO_WEB_DIST still takes a prebuilt bundle. The router's fallback answers an unmatched /api/* with 404 rather than the SPA shell, so a client expecting JSON gets a status it can read instead of HTML. Removes maestro-web and the [web] config section. An existing [web] block is ignored, not rejected. The installer deletes a leftover maestro-web.service on upgrade. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Miguel Palhas
co-authored by
Claude Opus 5
Claude Opus 5
parent
2ad2858fd5
commit
4fc90aabfb
+41
-64
@@ -51,22 +51,22 @@ The binary lands in `~/.cargo/bin/maestro` — make sure that's on your `$PATH`.
|
||||
|
||||
## Nix / NixOS
|
||||
|
||||
The repo is a flake. It exposes two packages and a Home Manager module:
|
||||
The repo is a flake. It exposes the `maestro` package, the SPA bundle it
|
||||
embeds, and a Home Manager module:
|
||||
|
||||
```sh
|
||||
nix run git+https://git.naps.pt/naps62/maestro -- list # the maestro binary
|
||||
nix build git+https://git.naps.pt/naps62/maestro#maestro-web
|
||||
```
|
||||
|
||||
`packages.maestro` is the unified CLI + daemon + TUI binary, wrapped so `tmux`
|
||||
and `git` are on its `PATH`. `packages.maestro-web` embeds a prebuilt SPA
|
||||
bundle — the Nix build points `MAESTRO_WEB_DIST` at `packages.webFrontend`, so
|
||||
`build.rs` skips pnpm entirely and no network fetch happens mid-compile. Set
|
||||
that variable yourself to reuse a bundle built elsewhere; leave it unset and
|
||||
the build falls back to running `pnpm install && pnpm build` in `web/`.
|
||||
`packages.maestro` is the unified CLI + daemon + TUI binary, with the browser
|
||||
SPA embedded, wrapped so `tmux` and `git` are on its `PATH`. The Nix build
|
||||
points `MAESTRO_WEB_DIST` at `packages.webFrontend`, so `build.rs` skips pnpm
|
||||
entirely and no network fetch happens mid-compile. Set that variable yourself
|
||||
to reuse a bundle built elsewhere; leave it unset and the build falls back to
|
||||
running `pnpm install && pnpm build` in `web/`.
|
||||
|
||||
Home Manager, with both services running as *user* units (same trust boundary
|
||||
as the tmux server they wrap):
|
||||
Home Manager, with the daemon running as a *user* unit (same trust boundary as
|
||||
the tmux server it wraps):
|
||||
|
||||
```nix
|
||||
{
|
||||
@@ -76,20 +76,18 @@ as the tmux server they wrap):
|
||||
imports = [ inputs.maestro.homeManagerModules.default ];
|
||||
|
||||
services.maestro = {
|
||||
enable = true; # installs the binary, runs `maestro daemon`
|
||||
web.enable = true; # runs `maestro-web`
|
||||
enable = true; # installs the binary, runs `maestro daemon`
|
||||
settings = {
|
||||
daemon.bind_addr = "127.0.0.1:7070";
|
||||
web.bind_addr = "0.0.0.0:8081";
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`settings` is written verbatim to `~/.config/maestro/config.toml` in the schema
|
||||
below; every field has a default, so `{}` writes no file at all. There is no
|
||||
auth layer — bind the web UI to a LAN or VPN address only on a trusted segment,
|
||||
never a public IP.
|
||||
below; every field has a default, so `{}` writes no file at all. The daemon
|
||||
serves the browser UI off that same address, and there is no auth layer — bind
|
||||
it to a LAN or VPN address only on a trusted segment, never a public IP.
|
||||
|
||||
`services.maestro.daemon.enable = false` installs the CLI and TUI without
|
||||
running a local daemon, for a host that only talks to another machine's.
|
||||
@@ -100,8 +98,8 @@ session alive.
|
||||
|
||||
## Thin builds for single-role hosts
|
||||
|
||||
The default install pulls in everything (`cli` + `daemon` + `tui`). Single-role
|
||||
hosts can opt out of unused dependencies:
|
||||
The default install pulls in everything (`cli` + `daemon` + `tui` + `web`).
|
||||
Single-role hosts can opt out of unused dependencies:
|
||||
|
||||
```sh
|
||||
# Daemon-only host — no CLI or TUI:
|
||||
@@ -113,6 +111,9 @@ cargo install --git https://git.naps.pt/naps62/maestro \
|
||||
--no-default-features --features cli --locked maestro
|
||||
```
|
||||
|
||||
Neither of those builds the browser UI: `web` is left out, so pnpm and node
|
||||
aren't needed. Add `--features daemon,web` to put it back.
|
||||
|
||||
The wizard always installs the default-feature build.
|
||||
|
||||
## The terminal UI: `maestro tui`
|
||||
@@ -185,53 +186,31 @@ An unknown name is rejected as an `[tui].theme` configuration error.
|
||||
The full action vocabulary is the `Action` enum in
|
||||
`crates/maestro-tui/src/action.rs`.
|
||||
|
||||
## Adding the browser UI (optional)
|
||||
## The browser UI
|
||||
|
||||
`maestro-web` is a separate binary that serves the SPA bundle and reverse-
|
||||
proxies API calls to a co-located `maestro daemon`.
|
||||
The daemon serves the SPA off its own listener. Open
|
||||
`http://127.0.0.1:7070/` — or whatever `[daemon].bind_addr` is — and the
|
||||
browser talks to the same process the CLI and TUI do. One binary, one port,
|
||||
nothing extra to install or start.
|
||||
|
||||
**Interactive install (default path).** The wizard offers it as an optional
|
||||
step right after the daemon flow:
|
||||
**Build prerequisite.** The `web` cargo feature is on by default and embeds the
|
||||
bundle at compile time: `build.rs` runs `pnpm install --frozen-lockfile &&
|
||||
pnpm build` in `web/`, so pnpm and node must be on `PATH`. Two ways around
|
||||
that — point `MAESTRO_WEB_DIST` at a bundle built elsewhere, or build with
|
||||
`--no-default-features` and pick the features you want (see *Thin builds*
|
||||
above).
|
||||
|
||||
```text
|
||||
Optional: install the browser UI (`maestro-web`)?
|
||||
Install maestro-web? [Y/n]
|
||||
```
|
||||
**Trust model.** There is no authentication layer: anyone who can reach
|
||||
`[daemon].bind_addr` can load the UI and drive every session on the host.
|
||||
Pick `127.0.0.1` for local-only, a WireGuard/LAN address for one-segment
|
||||
access, and never a public IP — the network perimeter is the only boundary
|
||||
Maestro has.
|
||||
|
||||
Press `Y` and it `cargo install`s `maestro-web`, drops a
|
||||
`~/.config/systemd/user/maestro-web.service` unit (ordered after
|
||||
`maestro.service`), reloads systemd, and offers to enable + start it. Re-runs
|
||||
of `./install.sh` detect the existing unit and refresh + restart silently.
|
||||
|
||||
Pass `--no-web` to skip the prompt entirely (headless hosts), or `--yes`
|
||||
with `--no-web` for non-interactive daemon-only installs. (Bare `--yes`
|
||||
without `--no-web` *skips* the web step too — opt in by re-running once
|
||||
interactively.)
|
||||
|
||||
**Frontend build prerequisite.** `maestro-web` embeds the SPA bundle at
|
||||
compile time, so before running the installer:
|
||||
|
||||
```sh
|
||||
pnpm -C web install --frozen-lockfile
|
||||
pnpm -C web build
|
||||
```
|
||||
|
||||
Or `just web` from a workspace checkout.
|
||||
|
||||
**Defaults.** `bind_addr = 127.0.0.1:8080`, `daemon_url =
|
||||
http://127.0.0.1:7070`. The `[web]` section of
|
||||
`~/.config/maestro/config.toml` overrides both — see
|
||||
`crates/maestro-web/README.md`.
|
||||
|
||||
**Trust model.** There is no authentication layer: anyone who can reach the
|
||||
bind address (of either the daemon or `maestro-web`) can drive every session on
|
||||
the host. Pick `127.0.0.1` for local-only, a WireGuard/LAN address for
|
||||
one-segment access, and never a public IP — the network perimeter is the only
|
||||
boundary Maestro has.
|
||||
|
||||
Headless hosts (servers, dev VMs) skip the prompt with `--no-web`. Hosts
|
||||
where you want browser access answer yes — both binaries end up in
|
||||
`~/.cargo/bin`.
|
||||
**Upgrading from the two-binary install.** Re-running `./install.sh` removes
|
||||
the old `maestro-web.service` unit for you; nothing to undo by hand. A leftover
|
||||
`[web]` block in `~/.config/maestro/config.toml` is ignored rather than
|
||||
rejected, but it no longer does anything — move the address you care about to
|
||||
`[daemon].bind_addr`.
|
||||
|
||||
## Flags
|
||||
|
||||
@@ -243,9 +222,7 @@ where you want browser access answer yes — both binaries end up in
|
||||
| `--no-locked` | Drop `--locked` from `cargo install` (resolves a fresh dep tree). |
|
||||
| `--exec-start <path>` | Override the systemd unit's `ExecStart` (default `~/.cargo/bin/maestro daemon`). |
|
||||
| `--no-systemd` | Skip the systemd step even if detected. |
|
||||
| `--no-web` | Skip the optional `maestro-web` install step. |
|
||||
| `--web-exec-start <path>` | Override the web unit's `ExecStart` (default `~/.cargo/bin/maestro-web`). |
|
||||
| `-y`, `--yes` | Non-interactive: install binaries + drop systemd unit + reload + enable, but **don't** auto-start the unit. Also skips the web step unless an existing `maestro-web.service` is being refreshed. |
|
||||
| `-y`, `--yes` | Non-interactive: install the binary + drop systemd unit + reload + enable, but **don't** auto-start the unit. |
|
||||
|
||||
## Where tmux sockets land
|
||||
|
||||
|
||||
Reference in New Issue
Block a user