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 maestrod and maestro end up persisted in ~/.cargo/bin.

Updating is the same command. Re-running ./install.sh detects an existing ~/.config/maestrod/config.toml and existing systemd unit, skips the configure prompt, refreshes the unit, and runs systemctl --user restart maestrod instead of start. No --update flag needed.

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 maestro-daemon and maestro-cli (pinned to the committed Cargo.lock via --locked).
2. Optionally runs maestrod configure to drop a ~/.config/maestrod/config.toml.
3. On systemd hosts, optionally writes a user unit at ~/.config/systemd/user/maestrod.service, reloads systemd, and offers to enable + start it.
4. On systemd hosts, also offers a local web UI unit (~/.config/systemd/user/maestro-web.service). When accepted, this also cargo installs maestro-registry and runs it bound to 127.0.0.1:8888 (override with --web-bind). Skip with --no-web (or just answer "n"); a remote registry deployment is the alternative.

Binaries land in ~/.cargo/bin — make sure that's on your $PATH.

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 <crate>).
--no-locked	Drop --locked from cargo install (resolves a fresh dep tree).
--exec-start <path>	Override the systemd unit's ExecStart (default ~/.cargo/bin/maestrod).
--no-systemd	Skip the systemd step even if detected.
--no-configure	Skip the maestrod configure step.
--no-web	Skip the optional local web-UI unit + maestro-registry install.
--web-bind <addr>	Loopback bind for the web UI (default 127.0.0.1:8888).
--web-exec-start <path>	Override the web unit's ExecStart (default ~/.cargo/bin/maestro-registry).
-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).

What the systemd unit looks like

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

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

[Service]
Type=simple
ExecStart=%h/.cargo/bin/maestrod
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Check status / logs:

systemctl --user status maestrod
journalctl --user -u maestrod -f

The optional maestro-web.service looks like:

[Unit]
Description=Maestro local web UI (maestro-registry on 127.0.0.1:8888)
Documentation=https://git.naps.pt/naps62/maestro
After=network-online.target maestrod.service
Wants=maestrod.service

[Service]
Type=simple
Environment=MAESTRO_REGISTRY_BIND_ADDR=127.0.0.1:8888
ExecStart=%h/.cargo/bin/maestro-registry
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Wants=maestrod.service (not Requires=) — the registry process is technically independent of the daemon, but the web UI has nothing to show without one connected, so we order this after maestrod and politely encourage it.

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-daemon
cargo install --git https://git.naps.pt/naps62/maestro --locked maestro-cli
maestrod configure
maestrod          # foreground; or wire your own service manager

Non-Linux hosts

The wizard works on macOS for the cargo install + maestrod configure parts. The systemd step is automatically skipped (probe of /run/systemd/system). launchd integration is not yet supported — start maestrod from your shell or your own service manager.