feat(cli): superset hosts add sets up any machine you can SSH into as a host

Merged
KI
1mo ago
+1179-15

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's machine 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

  1. 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 ssh and ~/.ssh/config are used.
  2. 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.
  3. Install or update with the official installer, pinned to this CLI's version, after a prompt (--yes skips it).
  4. Sign in. Mints an account API key named Host <hostname> (<id8>) and sends it to auth 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.
  5. Keep it running.
    • Linux: a systemd user unit (start --org in the foreground, Restart=on-failure, KillMode=process, so terminals survive a host restart). It offers loginctl enable-linger so the host runs with nobody logged in.
    • macOS: a LaunchAgent.
    • --no-service, or no systemd user session: start --daemon, with a warning.
  6. Wait until host.list reports the host id online, computed locally from the remote machine id. --name renames the host.
  7. Report if gh is 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.0 from the real installer.
  • Sign-in over stdin works. The key does not appear in ps on 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-setup fix), 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 remove unloaded 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 --daemon with the warning and came online; hosts remove cleaned 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 remove with an already-revoked key still stops the host and the terminal daemon.

Testing

  • bun test src/lib in 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.
  • shellQuote moved to lib/ 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 remove finds the key by the host's name. A box renamed since hosts add keeps 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 remove finds 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 add to configure a supported remote machine over SSH and start it as a background service where supported.
    • Added hosts remove to 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.
  • Bug Fixes
    • API keys supplied directly or through standard input are trimmed before validation.