Managing servers

Managing servers

When the JSON source is active, Settings → "Add / edit servers…" opens an editor to manage your connection list from a GUI — no hand-editing of JSON required.

What you can do

• Add a server with a form: Name, Group, User, Host or IP, Port, and an optional remote command.
• Edit any entry — including renaming it or moving it to another group.
• Duplicate an entry (the icon next to Edit): inserts a copy right below with -copy appended to the name and everything else carried over — handy for variants of the same host (e.g. shell vs. a remote command, or a different user/port).
• Reorder entries within a group by dragging them (use the ≡ handle / drag the row).
• Favorite an entry to pin it to a ★ Favorites section at the top of the dropdown — hover the star on a menu row, or use the Favorite toggle in the editor.
• Delete entries; a group with no entries left is removed automatically.

Entries with the same name (e.g. two "AdGuard" with different IPs) are kept distinct — editing, deleting or reordering one never affects the other.

Fields

Field	Notes
Name	Display name in the menu (required). Duplicate names are fine.
Group	Type a new group or pick an existing one. Empty → "Servers".
User	Optional; becomes user@host.
Host or IP	Required (in connection mode).
Port	Optional; omitted when 22.
Remote command	Optional. Runs on the server with a TTY: ssh -t user@host <command> — e.g. htop, tail -f /var/log/syslog. Empty = interactive shell.
Raw custom command	Toggle. Runs verbatim and ignores user/host/port — e.g. ssh -J jump root@10.0.0.5.
Favorite	Toggle. Pins the entry to the ★ Favorites section at the top of the menu.
Tags	Optional, comma-separated. Only shown when tags are enabled (Settings → General). Appear as badges in the menu and are searchable.

Favorites

Pin the servers you use most to a ★ Favorites section at the very top of the dropdown:

• Click the star that appears when you hover a row in the menu (filled = pinned), or use the Favorite toggle in the editor.
• The section is expanded by default when it has ≤ 5 entries, and is always collapsible.
• A favorite also still appears in its normal group — pinning is a shortcut, not a move.
• Favorites are stored as favorite: true on the JSON entry (only written when set). This works with the JSON source (ShuttleX can't write ~/.ssh/config).

Copy the SSH command

Right-click any server in the menu and choose "Copy SSH command" to put its built ssh … command on the clipboard — for sharing in chat, pasting into another terminal, or dropping into a ticket. Works for every source; the command is shell-quoted, so it's safe to paste as-is.

Tags (optional)

Tags are off by default. Enable them in Settings → General → "Enable server tags"; an optional comma-separated Tags field then appears per server. Tags show as small badges in the menu and are matched by search. Turning the feature off hides them everywhere again without removing them from the JSON (tags: [...], written only when set). A remote source may also carry tags — they're plain strings, never executed.

Running a command on a server

To pin a one-click action (monitor, restart, log tail), fill in Remote command:

• It keeps your User / Host / Port and runs ssh -t user@host '<command>'.
• The -t gives a TTY, so interactive tools like htop render correctly.
• Leave it empty for a normal interactive shell.

For something the connection fields can't express (jump hosts, tunnels), flip on Raw custom command and write the whole line yourself.

Tunnels (SSH port forwarding)

There's no dedicated tunnel UI, but you don't need one: a tunnel is just an ssh command, so add it as a Raw custom command entry and ShuttleX launches it in your terminal like any other connection. Examples:

# Local forward — reach a remote service on a local port
ssh -N -L 127.0.0.1:<local>:<remoteHost>:<remotePort> <host>

# Reverse forward — expose a local service on the remote
ssh -N -R <remotePort>:127.0.0.1:<local> <host>

# Dynamic / SOCKS proxy
ssh -N -D 127.0.0.1:<local> <host>

Notes:

• -N opens the tunnel without a shell and holds the terminal in the foreground — that window is the tunnel. Close it (or Ctrl-C) to drop the tunnel.
• Want it in the background instead? Add -f (e.g. ssh -fN -L …). It then detaches; stop it later with pkill -f "<part of the command>".
• Give the entry a clear name like Tunnel · DB 5432 so it's obvious in the menu (and tag it, e.g. tunnel, if you've enabled tags).

Safety

Host, IP and user are validated: values containing whitespace or shell metacharacters are rejected with an inline message (IPv6 in bracket notation like [2001:db8::1] is allowed). On top of that, every connection target is shell-quoted when the ssh command is built, so server data can't inject shell commands. See also Table import → Safety.

Every change writes the JSON file and snapshots the previous version — see Backups.