Server sources

Server sources

ShuttleX reads hosts from one of three sources, switchable in Settings → Server source.

~/.ssh/config

Hosts are read directly from your SSH config, including Include directives. Wildcard hosts (e.g. Host *) are ignored. This source is read-only — ShuttleX never writes to your SSH config.

JSON file

A dedicated file, by default at ~/.config/shuttlex/servers.json (created with sample entries the first time you switch to it). The path is configurable in Settings (Choose… / Reset to default), so you can point ShuttleX at a file you keep elsewhere (e.g. in a synced folder).

You can edit this file three ways:

• the in-app editor (see Managing servers),
• a table import,
• or by hand (Settings → "Edit file").

The last 3 versions are kept automatically — see Backups.

JSON format

{
  "groups": [
    {
      "name": "Production",
      "hosts": [
        { "name": "Web server", "user": "root", "host": "web1.example.com" },
        { "name": "Database", "user": "admin", "host": "db.example.com", "port": 2222 },
        { "name": "Database · htop", "user": "admin", "host": "db.example.com", "remoteCommand": "htop" },
        { "name": "Via jump host", "command": "ssh -J jump.example.com root@10.0.0.5" }
      ]
    }
  ],
  "hosts": [
    { "name": "Ungrouped", "host": "example.org" }
  ]
}

• host / user / port are assembled into ssh user@host -p port (the target is shell-quoted).
• remoteCommand runs a command on the server, built on top of host/user/port, with a TTY: ssh -t user@host <remoteCommand> — e.g. htop or tail -f /var/log/syslog.
• command runs verbatim — use it for jump hosts, tunnels, mosh, etc. It overrides host/user/port.
• favorite: true pins the entry to the ★ Favorites section at the top of the menu (see Managing servers). Only written when set.
• Top-level hosts (outside any group) appear under a group called "Servers".

Sharing your list across Macs (iCloud / Dropbox)

Since the JSON path is configurable, you can point it at a cloud-synced folder (iCloud Drive, Dropbox, OneDrive) to use the same server list on several Macs. ShuttleX re-reads the file every time you open the menu, so changes synced from another machine appear on the next open.

This is a lightweight setup, not built-in cloud sync — keep these caveats in mind:

• Edit on one Mac at a time. ShuttleX doesn't merge concurrent edits; if two Macs change the file at once, your cloud service may create a "conflicted copy" that ShuttleX won't reconcile.
• The version backups sync too. The servers.backup-…json files (see Backups) are written next to your JSON, so they also appear in the synced folder.
• With iCloud Drive, keep the file downloaded (avoid "Optimize Mac Storage" evicting it). If iCloud leaves a not-yet-downloaded placeholder, ShuttleX sees the path as missing and starts a fresh sample file instead.

Remote URL (team source)

Point ShuttleX at an https:// URL that serves the same JSON format (Settings → Server source → Remote URL). The list is read-only — a shared "single source of truth" your whole team can load from one place. It's fetched in the background and cached locally, so the menu keeps working offline; Reload (or reopening the menu) refreshes it.

Security model — inventory only. A remote source provides groups, names, host and port. Any command / remoteCommand in the file is ignored, so a compromised or malicious URL can't inject shell commands — at worst it points you at a different hostname, which still needs your own credentials and SSH host-key trust. HTTPS is required.

Your personal, local overrides. The shared list carries no user, and your favorites are personal — so each teammate keeps their own, stored locally on your Mac and kept across reloads:

• Login user — set a global Default user (Settings → Server source), and override it per server under Edit servers….
• Favorites — pin servers with the star in the menu, or the Favorite toggle under Edit servers….

Both are keyed by host:port, so they survive a remote reload and even renames in the shared list. An example inventory file shows the expected shape.