Windows and the server

Ship runs in two parts. A background server owns your tabs, panes and the programs in them. Running ship opens a window onto that server. Closing the window, or pressing alt-q, leaves everything running, and running ship again brings you back.

The first ship starts the server for you. Tab, pane and view commands also start it if needed. It restores your saved tabs, or opens one tab with a shell if there's nothing to restore. ship server status tells you whether a server is running, and ship server stop shuts it down, ending every program inside.

You can open Ship from several terminals at once. The windows share the work: the same tabs, programs, output, zoom and front panes in stacks. Scrolling and text selection in a pane are shared too. Each window picks its own tab and pane, folds its own sidebar and keeps its own mode. Panes are sized to fit the smallest window looking at that tab, so a bigger window shows some empty space around them. A program that asks to hear about focus, as many editors do, has it while any focused window has its pane selected.

If a window loses its connection to the server, it reconnects on its own.

On Linux and macOS, the server listens on a local socket that only your user account can open. ship server status prints its path in socket. On Linux it's usually $XDG_RUNTIME_DIR/ship/default.sock, and on macOS it's under $TMPDIR/ship/. Other user accounts get their own servers and can't connect to yours, but programs running as you can control it.

On Windows, Ship uses an owner-restricted named pipe instead. Explicit URLs use npipe:////./pipe/NAME rather than unix:///path. Windows support is best effort.

Each server has a name, and default is the one bare ship uses. To keep a separate set of tabs, pick another name:

ship --server-name scratch

That starts the scratch server if it isn't running, with its own saved tabs and logs. CLI commands take --server-name too, or set SHIP_SERVER_NAME once. Inside a pane, commands reach the server that owns the pane unless you pass --server-name or --server-url.

A new version doesn't replace a server that's already running. It keeps running the old version until you restart it, and restarting ends every program in it. When you update with ship update, it ends with what to do:

installed ship 0.2.0 (protocol 25); server ship 0.1.0 (protocol 24)
server must restart to stay in sync
restart the server: ship server stop && ship (ends running programs; tabs are restored)

If both versions speak the same protocol, it says the server is compatible and you can restart when it suits you. If they don't, ship won't open a window onto the old server and prints the same two versions and the restart command instead. Saved tabs come back with fresh shells, as after any restart. ship update itself never starts or stops a server.

The simplest way is to run Ship over SSH:

ssh otherbox -t ship

On Linux and macOS, you can instead run the client locally and forward the other machine's Unix socket. Run ship server status there to find its path, then replace /run/user/1000/ship/default.sock below with that path:

ssh -N -o StreamLocalBindUnlink=yes -L ~/.ship-otherbox.sock:/run/user/1000/ship/default.sock otherbox

Then, in another terminal:

ship --server-url unix://$HOME/.ship-otherbox.sock

Run ship on the other machine once first so its server is up. Passing --server-url makes Ship connect only to that socket, so it won't quietly start a local server if the tunnel isn't up. All the CLI commands take --server-url too, or set SHIP_SERVER_URL once. StreamLocalBindUnlink lets you rerun the ssh command after it exits, since it would otherwise refuse to replace the socket file it left behind.

The server has no network listener. Use SSH for remote access rather than exposing its socket through a web proxy. Ship rejects requests from web pages and expects HTTP requests addressed to localhost.

When creating a pane through the tunnel, use --cwd with a directory on the remote machine. Otherwise the CLI sends your local current directory, which may not exist there.

Sounds and clipboard copies happen on the machine you're sitting at. Through a tunnel, ship server stop stops the server but may report that it's still running, because the tunnel keeps accepting connections after the server is gone.