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
+24
-67
@@ -16,11 +16,9 @@ The bootstrap script builds `maestro-installer` into a temp directory, runs the
|
||||
wizard, and cleans up — only the unified `maestro` binary ends up persisted in
|
||||
`~/.cargo/bin`.
|
||||
|
||||
**Updating is the same command.** Re-running `./install.sh` detects an
|
||||
existing `[daemon]` section in `~/.config/maestro/config.toml` and an
|
||||
existing systemd unit, skips the configure prompt, refreshes the unit, and
|
||||
runs `systemctl --user restart maestro` instead of `start`. No `--update`
|
||||
flag needed. **The restart keeps your sessions:** the unit sets
|
||||
**Updating is the same command.** Re-running `./install.sh` detects an existing
|
||||
systemd unit, refreshes it, and runs `systemctl --user restart maestro` instead
|
||||
of `start`. No `--update` flag needed. **The restart keeps your sessions:** the unit sets
|
||||
`KillMode=process`, so systemd signals only the daemon — the tmux server (and
|
||||
every session) survives, and the new daemon re-adopts them on start. A unit
|
||||
written before this default lacks the line; re-run `./install.sh` to refresh it.
|
||||
@@ -43,11 +41,9 @@ The wizard:
|
||||
|
||||
1. Runs `cargo install` for the unified `maestro` crate (pinned to the
|
||||
committed `Cargo.lock` via `--locked`). The same binary hosts the CLI,
|
||||
the per-host daemon (`maestro daemon`), and the always-on registry
|
||||
(`maestro registry`), gated by Cargo features.
|
||||
2. Optionally runs `maestro daemon configure` to populate `~/.config/maestro/config.toml`
|
||||
(one shared TOML for the CLI, daemon, registry, and web).
|
||||
3. On systemd hosts, optionally writes a user unit at
|
||||
the per-host daemon (`maestro daemon`), and the TUI, gated by Cargo
|
||||
features.
|
||||
2. On systemd hosts, optionally writes a user unit at
|
||||
`~/.config/systemd/user/maestro.service`, reloads systemd, and offers to
|
||||
enable + start it.
|
||||
|
||||
@@ -55,15 +51,11 @@ The binary lands in `~/.cargo/bin/maestro` — make sure that's on your `$PATH`.
|
||||
|
||||
## Thin builds for single-role hosts
|
||||
|
||||
The default install pulls in everything (`cli` + `daemon` + `registry` + `tui`).
|
||||
Single-role hosts can opt out of unused dependencies:
|
||||
The default install pulls in everything (`cli` + `daemon` + `tui`). Single-role
|
||||
hosts can opt out of unused dependencies:
|
||||
|
||||
```sh
|
||||
# Registry server — no tmux/PTY/jwt-verifier code:
|
||||
cargo install --git https://git.naps.pt/naps62/maestro \
|
||||
--no-default-features --features registry --locked maestro
|
||||
|
||||
# Daemon-only host — no embedded web assets, no registry HTTP surface:
|
||||
# Daemon-only host — no CLI or TUI:
|
||||
cargo install --git https://git.naps.pt/naps62/maestro \
|
||||
--no-default-features --features daemon --locked maestro
|
||||
|
||||
@@ -81,8 +73,7 @@ in the default feature set, so a vanilla `cargo install maestro` builds it.
|
||||
Drop the `tui` feature to skip it on hosts that don't need the UI surface
|
||||
(`--no-default-features --features cli,daemon`).
|
||||
|
||||
It talks only to the **local** `maestro daemon` over `http://127.0.0.1:7070`
|
||||
by default; peer daemons reach you transparently via the catalog mirror.
|
||||
It talks to the local `maestro daemon` over `http://127.0.0.1:7070` by default.
|
||||
Override the daemon URL with `--daemon-url` or `$MAESTRO_DAEMON_URL`.
|
||||
|
||||
The `[tui]` section in `~/.config/maestro/config.toml` (or whatever path you
|
||||
@@ -117,8 +108,8 @@ The full action vocabulary lives in
|
||||
`maestro-web` is a separate binary that serves the SPA bundle and reverse-
|
||||
proxies API calls to a co-located `maestro daemon`.
|
||||
|
||||
**Interactive install (default path).** The wizard now offers it as an
|
||||
optional step right after the daemon flow:
|
||||
**Interactive install (default path).** The wizard offers it as an optional
|
||||
step right after the daemon flow:
|
||||
|
||||
```text
|
||||
Optional: install the browser UI (`maestro-web`)?
|
||||
@@ -150,9 +141,11 @@ http://127.0.0.1:7070`. The `[web]` section of
|
||||
`~/.config/maestro/config.toml` overrides both — see
|
||||
`crates/maestro-web/README.md`.
|
||||
|
||||
**Trust model.** Anyone who can reach the bind address can use it. Pick
|
||||
`127.0.0.1` for local-only, a WireGuard/LAN address for one-segment access,
|
||||
never a public IP without adding auth first.
|
||||
**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
|
||||
@@ -168,10 +161,9 @@ 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-configure` | Skip the `maestro daemon configure` step. |
|
||||
| `--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-run `configure` or auto-start the unit (those need real config). Also skips the web step unless an existing `maestro-web.service` is being refreshed. |
|
||||
| `-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. |
|
||||
|
||||
## Where tmux sockets land
|
||||
|
||||
@@ -190,44 +182,6 @@ Pick `/tmp` if the daemon must outlive your login session and you can't run
|
||||
tmux sockets with it). The env var `MAESTRO_DAEMON_TMUX_TMPDIR` takes
|
||||
precedence over the file.
|
||||
|
||||
## Cross-host attach (perimeter setup)
|
||||
|
||||
Attaching to a session that lives on **another** host is brokered over the "T2"
|
||||
transport, which only works when both daemons advertise a **matching
|
||||
`perimeter_id`** and the session's owner advertises a **reachable
|
||||
`private_addr`**. These default to unset, and without them every cross-host
|
||||
attach fails — the registry resolves the session but returns no perimeter
|
||||
candidate, so the attaching daemon rejects it (`no_perimeter_candidate`) and the
|
||||
browser pane shows the reason and closes. Same-host attach is unaffected.
|
||||
|
||||
Set both on **every** host in `~/.config/maestro/config.toml`:
|
||||
|
||||
```toml
|
||||
[daemon]
|
||||
# Identical on every daemon that should reach each other — name it after your
|
||||
# VPN/LAN segment. Two daemons broker to each other only when these match.
|
||||
perimeter_id = "wg-home"
|
||||
# THIS host's address as its peers reach it on that perimeter (host:port of the
|
||||
# daemon's bind_addr). Per-host — never the same value on two daemons.
|
||||
private_addr = "10.0.0.7:7070"
|
||||
```
|
||||
|
||||
It's both-or-neither: setting only one is ignored with a startup warning. A
|
||||
daemon started with no perimeter configured logs a `WARN` saying cross-host
|
||||
attach is unavailable. (T1 direct-WSS was dropped — NAP-235 — and T3 relay isn't
|
||||
implemented — NAP-238 — so T2 is currently the only cross-host path.)
|
||||
|
||||
## Peer attach trust model
|
||||
|
||||
There is no per-peer allow-list. The operator's network perimeter (VPN/firewall)
|
||||
is the trust boundary for *which hosts can connect*; every daemon reachable on
|
||||
the perimeter may broker-attach to any other. Attach is still authenticated: the
|
||||
registry mints a short-lived, pair-scoped JWT bound to the target daemon and the
|
||||
specific session (`iss`/`aud`/`sid`/`exp`), which the target verifies — so a
|
||||
reachable host still can't attach to a session it wasn't handed, or replay a
|
||||
token elsewhere. (NAP-339 dropped the earlier `[daemon.policy].allow_inbound`
|
||||
gate; re-introducing a per-pair allow-list later is a verify-time change.)
|
||||
|
||||
## What the systemd unit looks like
|
||||
|
||||
The wizard writes a *user* unit (`systemctl --user`), since `maestro daemon`
|
||||
@@ -273,13 +227,16 @@ script avoids that by installing to a scratch dir.
|
||||
|
||||
```sh
|
||||
cargo install --git https://git.naps.pt/naps62/maestro --locked maestro
|
||||
maestro daemon configure
|
||||
maestro daemon # foreground; or wire your own service manager
|
||||
```
|
||||
|
||||
Every setting has a default, so `~/.config/maestro/config.toml` is optional —
|
||||
create it only to change the bind address, worktree root, spawn presets, or TUI
|
||||
keymap.
|
||||
|
||||
## Non-Linux hosts
|
||||
|
||||
The wizard works on macOS for the `cargo install` + `maestro daemon configure`
|
||||
parts. The systemd step is automatically skipped (probe of
|
||||
The wizard works on macOS for the `cargo install` part. The systemd step is
|
||||
automatically skipped (probe of
|
||||
`/run/systemd/system`). launchd integration is not yet supported — start
|
||||
`maestro daemon` from your shell or your own service manager.
|
||||
|
||||
Reference in New Issue
Block a user