maestro/docs/INSTALL.md

Installing Maestro

The repo is private, so grab install.sh while signed in to gitea, then run it:

1. Open https://git.naps.pt/naps62/maestro/src/branch/main/install.sh, click Raw, save as install.sh. Or from any existing clone:

   git show origin/main:install.sh > install.sh
   

2. Run it:

   chmod +x install.sh && ./install.sh
   

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 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.

Inside the script, cargo install --git https://git.naps.pt/naps62/maestro … uses your already-configured git credentials for this host (HTTPS helper or SSH agent). If only SSH is set up:

MAESTRO_REPO_URL=ssh://git@git.naps.pt/naps62/maestro ./install.sh

Pass flags through to the wizard after ./install.sh:

./install.sh --yes --no-systemd

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 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.

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:

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/.

Home Manager, with both services running as user units (same trust boundary as the tmux server they wrap):

{
  inputs.maestro.url = "git+https://git.naps.pt/naps62/maestro";

  # in your Home Manager configuration:
  imports = [ inputs.maestro.homeManagerModules.default ];

  services.maestro = {
    enable = true;      # installs the binary, runs `maestro daemon`
    web.enable = true;  # runs `maestro-web`
    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.

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.

The daemon unit carries the same KillMode=process as the wizard-written one, so systemctl --user restart maestro-daemon leaves the tmux server and every 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:

# Daemon-only host — no CLI or TUI:
cargo install --git https://git.naps.pt/naps62/maestro \
  --no-default-features --features daemon --locked maestro

# CLI-only client (no local daemon, no TUI):
cargo install --git https://git.naps.pt/naps62/maestro \
  --no-default-features --features cli --locked maestro

The wizard always installs the default-feature build.

The terminal UI: maestro tui

maestro tui is the keyboard-and-mouse driven terminal UI client. It ships 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 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 pass via the global --config flag) controls the keymap. Shipped defaults cover every v1 action — only override what you want to change:

[tui]
leader = "ctrl-a"            # one byte that escapes Insert mode
chord_timeout_ms = 1000      # how long to hold a partial chord like `g`

[tui.keymap.normal]
"i"            = "EnterInsert"
"s"            = "OpenSpawnModal"
"x"            = "KillHighlighted"
"?"            = "ShowHelp"
"ctrl-t"       = "NewTab"
"g t"          = "NextTab"
"ctrl-w h"     = "FocusSidebar"
"enter"        = "AttachHighlighted"

[tui.keymap.insert]
# (leader is added automatically as LeaveInsert; only override here when you
# want extra Insert-mode bindings)

The full action vocabulary lives in docs/superpowers/specs/2026-05-28-maestro-tui-design.md §3.8.

Adding the browser UI (optional)

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 offers it as an optional step right after the daemon flow:

Optional: install the browser UI (`maestro-web`)?
Install maestro-web? [Y/n]

Press Y and it cargo installs 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:

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.

Flags

Flag	Purpose
--git <url>	Install from a different git repo (default: this one).
--branch <name>	Pin a branch with --git.
--path <dir>	Install from a local workspace checkout (--path + -p maestro).
--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.

Where tmux sockets land

maestro daemon defaults TMUX_TMPDIR to $XDG_RUNTIME_DIR (= /run/user/$UID) so a plain tmux ls in your shell — which typically uses the same env var — sees maestro-managed sessions. Override in ~/.config/maestro/config.toml:

[daemon]
tmux_tmpdir = "/tmp"

Pick /tmp if the daemon must outlive your login session and you can't run loginctl enable-linger (the runtime dir is wiped on logout, taking the tmux sockets with it). The env var MAESTRO_DAEMON_TMUX_TMPDIR takes precedence over the file.

What the systemd unit looks like

The wizard writes a user unit (systemctl --user), since maestro daemon runs per-user and uses tmux sockets under $XDG_RUNTIME_DIR. Body:

[Unit]
Description=Maestro per-host daemon
Documentation=https://git.naps.pt/naps62/maestro
After=network-online.target

[Service]
Type=simple
ExecStart=%h/.cargo/bin/maestro daemon
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Check status / logs:

systemctl --user status maestro
journalctl --user -u maestro -f

Running the wizard without the bootstrap script

If you'd rather skip the script:

cargo install --git https://git.naps.pt/naps62/maestro maestro-installer
maestro-install

This leaves maestro-installer permanently in ~/.cargo/bin — the bootstrap script avoids that by installing to a scratch dir.

Fully manual install (no wizard)

cargo install --git https://git.naps.pt/naps62/maestro --locked maestro
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 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.