feat(cli): superset hosts add sets up any machine you can SSH into as a host
Links
- Plan:
plans/20261010-add-host-over-ssh.md(phase 1). This depends on #8386, which is merged and deployed.
Summary
superset hosts add <ssh-target>turns a machine you can SSH into into a Superset host in one command. Nothing is typed on the other machine. This copies herdr'smachine add.superset hosts remove <ssh-target>undoes it.superset auth login --api-key=-reads the key from stdin, so it never appears in argv or shell history.
How it works
- Connect. One ssh ControlMaster connection is used for the whole run, so password, MFA and host-key prompts come up once. Later steps reuse it in BatchMode. The user's own
sshand~/.ssh/configare used. - Probe. One script reports the platform, glibc or musl, the machine id, an existing CLI and its version, systemd, linger and
gh. Each refusal shows its reason and the fix:- musl, Windows and unsupported architectures;
- an empty
/etc/machine-id, which would collide with every clone of the image; - the machine the command runs on.
- Install or update with the official installer, pinned to this CLI's version, after a prompt (
--yesskips it). - Sign in. Mints an account API key named
Host <hostname> (<id8>)and sends it toauth login --api-key=-over stdin. A working sign-in is kept on re-run, and a failed sign-in revokes the key it just made. - Keep it running.
- Linux: a systemd user unit (
start --orgin the foreground,Restart=on-failure,KillMode=process, so terminals survive a host restart). It offersloginctl enable-lingerso the host runs with nobody logged in. - macOS: a LaunchAgent.
--no-service, or no systemd user session:start --daemon, with a warning.
- Linux: a systemd user unit (
- Wait until
host.listreports the host id online, computed locally from the remote machine id.--namerenames the host. - Report if
ghis missing or signed out on the remote.
A re-run is a repair: it updates an outdated CLI and restarts the service only if the unit or the binary changed.
Manual QA
Run against a Docker Ubuntu 24.04 box with systemd and sshd, and a Docker Alpine box, using the production API:
- Fresh box: install pinned to
cli-v1.37.0from the real installer. - Sign-in over stdin works. The key does not appear in
pson the box. - systemd service started, linger enabled, host online in about 15 s.
- Re-run: "Already signed in", "service unchanged", online.
-
docker restart(a reboot) with no login sessions: the host came back on its own. -
--no-service: the daemon outlives the SSH session (parent is PID 1). -
hosts remove: the unit is gone, signed out, no host processes left, key revoked (revokedKeys: 1). - Refusals: Alpine (musl), empty machine-id (shows the
systemd-machine-id-setupfix), unknown host (ssh hints). - macOS 15.7 VM (tart, arm64, its own hardware UUID): install from the release, LaunchAgent started, online. A re-run reported "unchanged". After a VM reboot the host came back by itself.
hosts removeunloaded the agent, stopped all host processes, and revoked and signed out. This found the 32-character key-name limit, now fixed. - Fly Sprite (Ubuntu 26.04, x86_64, no systemd): it fell back to
start --daemonwith the warning and came online;hosts removecleaned up. - After the review fixes, on Ubuntu: a key revoked behind the host's back is repaired by a re-run, which mints a new key, restarts the service (new PID) and brings the host back online.
hosts removewith an already-revoked key still stops the host and the terminal daemon.
Testing
bun test src/libin packages/cli: 242 pass, including new tests for platform, machine-id, probe parsing and service files.bun run lint; CLI typecheck is clean.
Design decisions
- SSH only for setup. After setup the host reaches the desktop through the relay like any other host, so no SSH session stays open.
- Account API key for now. A scoped, host-bound credential is phase 3 of the plan.
--api-key=-rather than--api-key -. The CLI parser reads a bare-as a flag.shellQuotemoved tolib/with no backslashes. fish reads backslashes inside single quotes, and ssh hands every command to the user's login shell.
Known limitations
- macOS: a LaunchAgent starts only after a GUI login. A Mac that boots to the login window runs the host only once someone logs in. The test VM logs in automatically.
hosts removefinds the key by the host's name. A box renamed sincehosts addkeeps its key, which can be revoked in Settings → API keys.- The host row stays listed (offline) after
hosts remove; delete it in Settings → Hosts. - Docs are held until the desktop entry point (phase 2) lands too.
Summary by cubic
superset hosts add <ssh-target> turns any machine you can SSH into into a host in one command — nothing is typed on the remote. It probes the machine, refuses musl Linux, unsupported architectures, and empty machine ids, installs or updates the CLI pinned to this version, signs it in with a named API key sent over stdin, and runs the host as a systemd user unit or LaunchAgent (or a plain daemon with --no-service). hosts remove <ssh-target> stops the host, removes the service, and revokes its key.
auth login --api-key=- reads the key over stdin so it never lands in argv or shell history. Re-running hosts add repairs a stale CLI or stopped service; a fresh sign-in restarts the host, so repairing a revoked key brings it back too. The setup requires a host runtime next to the CLI, and stop --org accepts an id so add/remove can stop the remote host even with a revoked key. Host API key names are capped at 32 characters so the mint never fails on long hostnames.
Notes for review
hosts removefinds the key by host name and only signs the host out when it revoked a key; the host row stays listed offline until deleted in Settings.- One ControlMaster connection carries the whole run, so password and MFA prompts appear once.
Summary by CodeRabbit
- New Features
- Added
hosts addto configure a supported remote machine over SSH and start it as a background service where supported. - Added
hosts removeto stop a remote host, remove its service, and revoke its matching host credential. - Login can read an API key from standard input when
-is provided. - The stop command can target an organization by ID, slug, or name.
- Added
- Bug Fixes
- API keys supplied directly or through standard input are trimmed before validation.