Remote SSH sessions
Ghostex supports remote SSH machines in the sidebar. Add a Mac running Ghostex, browse its live sessions over gxserver, and attach through a local Ghostty terminal that SSHs into the remote login shell and runs ghostex attach with the stable session-id contract.
Remote machines in Settings
Settings owns the saved remote machine list. Each machine requires a user-visible name and SSH host. Live connection state, projects, sessions, and gxserver tokens refresh from the remote daemon — not from static settings.
| Option | What it does |
|---|---|
name | Display name shown in the sidebar remote section. |
sshHost | Hostname or IP (Tailscale name recommended). |
sshPort | Optional SSH port (1–65535). |
sshIdentityFile | Optional path to an SSH identity file. |
sshPasswordSaved | Boolean marker only — passwords are stored in macOS Keychain, not in settings JSON. |
Prerequisites
- Install Tailscale on both Macs (or use another reachable SSH path) and enable macOS Remote Login.
- Install Ghostex on the remote Mac with ghostex/gx available in the SSH login shell.
- Set session persistence to zmx (default for new installs) for the smoothest attach flow.
- Keep Ghostex open on the remote Mac so gx can list live sessions; zmx keeps terminal sessions durable.
- Keep the remote Mac awake while attaching from another device.
SSH attach contract
Clicking a remote session on macOS opens a local Ghostty terminal that SSH-attaches with a forced PTY and runs:
ghostex attach --session-id <id> --project-id <id>This matches Android and iOS attach semantics. Mobile and desktop clients rely on the stable Ghostex id contract — not raw gxserver attach metadata alone.
CLI from SSH
ssh user@mac-tailscale-host
# List sessions and note the left-column alias
gx sessions
# Attach to session 1
gx a 1
# Wake, focus, or sleep from remote
gx wake 1
gx focus 1
gx sleep 1
# Title selector when alias is not handy
gx a "project:session title"Remote gxserver presentation
When a remote machine connects, Ghostex subscribes to gxserver presentation events over SSH. The sidebar shows remote projects, sessions, and activity states. If the live bridge is unavailable, Ghostex can fall back to persisted sidebar data for session inventory.
- Remote attach panes use a hidden carrier project for the native Ghostty surface.
- The sidebar focus ring stays on the remote session row, not the local carrier.
- Remote Git agent workflows appear as visible remote sessions.
Authentication
- SSH identity file — configure per machine in Settings.
- Keychain password — save from the remote machine connection UI; stored only in macOS Keychain.
- Passwords are one-shot native commands and never persisted in settings drafts.
Android and iOS
Mobile companions use the same attach contract over Tailscale SSH. Android lists ZMX-backed sessions and attaches with stable session ids. iOS uses GhostexSidebarStore to refresh sessions and run attach actions over SSHJ transport.
See the Android and iOS companion docs for device-specific setup.