Server sources

Server sources

ShuttleX reads hosts from one of two 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.