SSH and tmux

SSH and tmux

When you mark a pane as an SSH connection, ClusterSpace wraps it in tmux automatically — so closing the pane (or losing your network, or crashing the app) never costs you the running command.

---

SSH Server manager

Open the manager:

• Status bar → SSH button
• Right-click any pane → SSH Servers
• Command palette → "ssh servers"

Backed by src/main/credentials-store.ts (encrypted via Electron safeStorage, fallback to base64 with a warning if the OS keychain is unavailable).

Adding a server

Field	Notes
Name	Display label only
Host	Hostname or IP
Port	Default 22
User	SSH user
Auth	Key (path to private key, optional passphrase) or Password (stored in keychain)
Initial directory	Optional cd <path> after login

Editing / removing

Click any row in the manager to edit. Removing a server doesn't kill running PTYs that used it; they keep running until you explicitly close them.

---

How an SSH pane is spawned

Under the hood, ClusterSpace invokes:

ssh -t user@host -p <port> [-i <keypath>] -- tmux new-session -A -s <session-name>

• -t forces a pseudo-tty (needed for interactive tmux)
• -A attaches if <session-name> already exists, otherwise creates it
• <session-name> defaults to clusterspace-pane-<paneId-short> — unique per pane, so two panes connecting to the same host don't echo into each other

For password auth, ClusterSpace watches the SSH prompt and injects the saved password via the PTY input stream.

---

tmux session naming

By default each new pane gets a unique session name: clusterspace-pane-<short>. You can override this at any time:

Right-click pane → Attach to tmux session… → pick from the list (key-auth) or type a name (any auth).

Why unique names?

Two panes on the same host with the same session name would echo each other (both attached to the same tmux client). Unique names give you independent windows; if you want shared sessions, set them up explicitly via the picker.

Legacy migration

The app was originally called Fleet Term; pre-rename sessions used names like fleet-term-pane-<short> or fleet-term-<server-short>. After the rename, your existing remote sessions kept their old names. The tmux picker shows a Legacy suggestion chip when it detects you're on a server you used pre-rename — one click attaches to the old name.

If you can't find a session you remember running, run tmux ls on the host directly to see what's actually there, then type the name in the picker manually.

---

Tmux Session Picker

The picker (src/renderer/components/TmuxSessionPicker.tsx) is a small modal with:

• Existing sessions — auto-detected via ssh user@host tmux list-sessions -F '#S'. Only works with key auth (no automatic tmux ls for password auth).
• Manual entry — type a session name; we tmux new-session -A -s <name> it (idempotent — attaches if it exists, creates if not).
• Legacy suggestion — one-click for the old fleet-term-naming convention if applicable.
• Cancel — close the picker without changing anything.

The same picker is used for adding a new tab to an existing pane (see Per-Pane-Tabs).

---

Close-pane confirm dialog

Closing an SSH pane (× button or context menu → Close) opens a confirm dialog:

Option	What it does
Cancel	Don't close anything
Close pane, keep session (default)	Kills local PTY; remote tmux session keeps running. Reattach later.
Close pane and destroy session	tmux kill-session -t <name> then kill PTY. The session is gone for good.

This matches the close-tab behavior in Per-Pane-Tabs.

---

Nested tmux gotcha

If your shell auto-starts tmux (e.g., your .bashrc does tmux attach || tmux), ClusterSpace's SSH command will nest you inside two layers of tmux. The outer one is the one ClusterSpace manages; the inner one is yours.

Two workarounds:

• Guard your auto-tmux line with [ -z "$TMUX" ] so it only fires when not already in a session.
• Use a per-pane override via Attach to tmux session… to attach explicitly to the inner one you want.

---

What requires tmux?

Feature	Needs tmux on host?
Basic SSH terminal	No — set the pane to plain SSH (no auto-tmux wrap) via the right-click menu
Session persistence across pane close	Yes
Multi-tab pane to same host	Yes (each tab = its own tmux session)
Reattach after app restart	Yes

If you're on a host without tmux and can't install it, you can still use ClusterSpace as a plain SSH terminal — you'll just lose persistence.

---

See also

• Per-Pane-Tabs — multiple SSH+tmux sessions in one pane
• Terminal-Panes — the renderer and clipboard story
• Saved-Logins — for browser saved credentials (not SSH)
• Troubleshooting — common SSH/tmux errors