Remote Workspaces

imux extends its workspace model to remote hosts over SSH. Each remote workspace gives you a terminal, file explorer, and full workspace context on the remote machine.

ICC SSH Command

Create a managed remote workspace with a single command:

• Run icc ssh user@host to create a new remote workspace connected to the target machine.
• The command reads your OpenSSH config (~/.ssh/config) for host aliases, ports, identity files, and proxy jump settings.
• The remote workspace appears in your sidebar alongside local workspaces, with the hostname as the workspace label.

macOS Keychain Credential Storage

imux stores remote credentials securely in the macOS Keychain:

• Passwords and passphrases are saved in the login keychain, never in plaintext config files or environment variables.
• The Keychain entry is scoped to the SSH host, so credentials are automatically available on reconnect without re-prompting.
• You can manage stored credentials through the Keychain Access app or revoke them from imux Settings.

Remote File Explorer

Browse and edit files on the remote host through a visual tree view:

• The remote explorer shows the real file tree from the remote host, not a local mirror or cached copy.
• Click any file to open it in an in-app editor with syntax highlighting. Save writes directly back to the remote host.
• The explorer only appears after the SSH connection is established, so you always browse live remote state.

Multi-Hop SSH via Bastion Hosts

Connect to hosts behind bastion or jump servers using your existing SSH config:

• Define ProxyJump or ProxyCommand in your ~/.ssh/config, and imux follows the same chain automatically.
• Each hop authenticates using the credentials defined in your SSH config or stored in Keychain.
• The remote workspace shows the final target hostname, keeping the connection chain transparent.

Auto-Reconnect on Network Drops

imux automatically re-establishes dropped SSH connections:

• When the network drops or the remote host disconnects, imux detects the broken session and begins reconnection.
• Stored credentials are reused, so reconnection is silent when the network recovers.
• The workspace state (open files, working directory) is preserved across reconnects where possible.

Reverse SSH Forwarding

Remote tools can communicate back to your local imux instance:

• imux sets up a reverse SSH tunnel so remote processes can reach your local imux socket.
• This enables remote agents and scripts to send notifications, update sidebar state, and trigger workspace actions on your local machine.
• The tunnel is established during workspace creation and torn down when the workspace closes.

The iccd-remote Helper Binary

Each remote workspace deploys a small helper binary to the remote host:

• iccd-remote speaks newline-delimited JSON over stdio, using RPC groups such as hello, ping, proxy.*, and session.*.
• It is auto-deployed during workspace creation and requires no manual installation on the remote host.
• The binary is updated automatically when imux releases a new version, matching the local app's protocol version.