Remote sessions

A remote session is a Shelbi project that lives on another machine (a devbox, a build server, a Mac mini in the closet) opened from the Shelbi on the machine in front of you. The project, its daemon, its orchestrator and its workspaces all keep running over there; you just look in and drive.

This is different from remote workspaces, where your hub dispatches agents to slots on other machines. A remote session connects to a whole other Shelbi: its own hub, its own projects.

Connecting

Open Connect to Remote Session from any of these:

• the launch screen's Connect to remote button,
• the Shelbi menu, Connect to Remote Session… (desktop),
• the command palette (Connect to Remote Session…),
• a terminal: shelbi remote connect <host> [project].

It is the same two-step dialog wherever you start:

1. SSH host. Type an SSH alias from your ~/.ssh/config (devbox) or user@hostname, then Find Sessions.
2. Choose session. Shelbi signs in, shows the user it is Connected as, and lists that machine's projects with their folders. Pick one and Connect. Change host goes back to step 1.

Every project you connect to lands in Recent remote sessions on the launch screen, newest first, so next time it is one click. The list keeps the eight most recent, one entry per host, user and project.

What a remote session looks like

How a remote session opens depends on the Shelbi on the other machine.

The same version as yours: the full window. The desktop app opens its whole window for the project, as it does for a project on this Mac: the sidebar, the Orchestrator, the Issues board and task pane, Workspaces, Activity, Machines and Settings. The title bar and the sidebar name the user and host (jlong@devbox), and the project switcher lists that machine's projects. Everything you do runs on the other machine: moving a card, starting a review, toggling Zen Mode, saving a workflow or a workspace in Settings, checking a machine. Edit opens the file in that machine's $EDITOR, in a terminal there, and a file you drop on one of its terminals is copied there and its path pasted.

Any other version: the terminal view. The desktop app opens the other machine's own Shelbi in its terminal interface, running over SSH (ssh -t <host> shelbi --project <project>), in a window of its own with the host and project in the title bar. A line under the title bar says why:

Shelbi on devbox is 0.12.1 and this Mac has 0.13.0, so it opens in its terminal view. Update both to get the full window.

The full window needs exactly the same version on both machines. Another patch release (0.13.0 and 0.13.1) or a Shelbi from before the full window opens the terminal view. Update both machines to the same release to get the full window.

From a full window you can still use the terminal view: choose View ▸ Open in Terminal View, or Open in Terminal View in the command palette. It opens in a window beside the full one, on the same project.

In the TUI, a remote session always opens the other machine's Shelbi in the terminal: it takes over until you quit it, and then you're back.

A full window leaves a few things to the other machine itself. Add Project, New Window, Quit Shelbi and Detach Other Clients are grayed out with the reason; run them there.

A workspace the other machine's project runs on yet another of its machines streams into the full window too. The other machine reaches it the way it always does, over its own connection to that machine, and passes the terminal through, so your Mac needs no route to that machine and no credentials for it.

When the connection drops

Sessions on the other machine never depend on your connection: agents keep working when your Wi-Fi blinks or your laptop sleeps. If SSH drops, Shelbi shows "Reconnecting to host… (attempt N)" and tries again, quickly at first and then backing off, until the machine answers. You land back where you were. A workspace on yet another machine reconnects the same way when either connection drops, yours to the other machine or the other machine's to it.

In the TUI (and with shelbi remote connect), press Esc to stop reconnecting. A reconnect never starts the other machine's Shelbi: if it has stopped, the retries end with "Shelbi isn't running on host." and you're offered Start Shelbi instead.

A full window also checks the other machine's version each time it reconnects, since Shelbi there may have been updated while you were away. If the versions no longer match, the window closes its terminals, stops sending anything to that machine, and shows Reopen. Reopen opens the project again in whichever window now fits: the full window if the versions match again, otherwise the terminal view.

SSH and credentials

Shelbi uses your existing SSH setup:

• It runs your own ssh, so your keys, ssh-agent, ~/.ssh/config aliases, jump hosts and Tailscale all apply.
• When SSH needs something from you, Shelbi asks in a macOS dialog. A host that wants a password, a key whose passphrase isn't loaded in your agent, or a one-time code shows SSH's own prompt ("user@host's password:", "Enter passphrase for key …") with a hidden field. OK carries on connecting; Cancel stops with "Couldn't sign in to host". A wrong password is asked again, as many times as SSH allows.
• Every dialog starts with "SSH sign-in to host" and "host asks:" above the prompt. A one-time-code prompt is text the other machine sends, so treat it as that machine's question: Shelbi never asks for your Mac's own password.
• A machine you haven't connected to before shows SSH's host-key question, with the key's fingerprint, in the same kind of dialog, with Yes and No. No is the default, so pressing Return refuses; accepting the key takes a click on Yes. Shelbi never answers it for you.
• You're asked once. The steps of a connection, the session's terminal and a full window's link share one SSH connection, which stays open for ten minutes after you leave.
• If a full window loses its connection, it asks once to reconnect. If you click Cancel, it stops asking and shows Sign In until you're ready.
• Shelbi never stores, logs or sees your password: the dialog hands it straight to ssh.
• Where no dialog can be shown (on Linux, or when Shelbi itself runs over SSH rather than in your Mac's desktop session), SSH runs in batch mode and never prompts. A host that wants a password then fails with "Couldn't sign in to host" and a hint to add a key (ssh-copy-id <host>) or load yours with ssh-add. Set SHELBI_ASKPASS=never to get that behavior on a Mac too.

The other machine's daemon

Shelbi does not start or stop the other machine's daemon on its own. If Shelbi is installed there but not running, the dialog says so and offers Start Shelbi, which starts it the same way a client on that machine would. Stopping it is up to you, on that machine.

Requirements and errors

The other machine needs Shelbi installed and at least one project. The dialog explains each thing that can go wrong:

To see what a remote client will find on a machine, run shelbi remote list on it.

See also

• shelbi remote: what a machine reports to remote clients.
• Workspaces: dispatching agents to other machines from your own hub.