Going remote

The backend daemon runs where your GPUs and data are, the frontend window runs on the machine in front of you, and the two talk over SSH: the frontend dials each host with its own ssh child, and browser pages ride that same connection. If the frontend closes, the agents and the REPL keep running on the server.

Session rows and their work-state colours.

1. Install the backend on the server

On the server (Linux), install the headless backend role:

curl -fsSL https://raw.githubusercontent.com/kalidke/ship-of-tools/main/scripts/install.sh | bash -s -- --be-only

By default this installs and starts the systemd --user unit sotd.service, so the daemon outlives your SSH login. (--no-service skips the unit when something else supervises sotd; a server whose home other hosts share is covered in Install details.)

Every role needs Julia 1.12 or newer (installed with juliaup if missing) and gets the skills and hooks; see What the installer changes.

If the server's home directory is itself on NFS, point the daemon's state root at local disk first — see A session will not start on a shared home.

2. Install the frontend on your machine

On the laptop or desktop, install the frontend role and name the server by its SSH alias (the one you use for ssh myserver):

curl -fsSL https://raw.githubusercontent.com/kalidke/ship-of-tools/main/scripts/install.sh | bash -s -- --backend myserver

On Windows, use the release zip and scripts\install-shortcut.ps1, as described under Install.

3. Launch

Run sot-launch (or the desktop entry). The launcher applies any staged update and starts the frontend, which dials each host with its own ssh child. The daemon on the server is started once and survives across launches.

With more than one server, the frontend connects to every backend host listed in hosts.toml. One machine, the hub, holds the canonical copy, and sotd topology sync fetches it on every launch; see Hosts mode and Configuration files.

Reconnecting

The connection can drop (laptop sleep, network change, SSH timeout) without losing anything on the server. The frontend reconnects on its own; F5 retries at once. Agent sessions do not depend on the connection: each runs under its own supervisor on the server (see Sessions and persistence).

Browser pages

o opens HTML, video and Pluto pages in your own browser, Shift+W opens a file's built documentation site, and wglshow opens an interactive WGLMakie figure. These work the same with a remote backend and need no extra SSH setup. How the traffic is carried is described under Interactive figures in the browser.

Next steps

• A second frontend — attach a desktop and a laptop to the same backend.

• Enrolling a host — make a server reachable from every frontend.

• Troubleshooting — when a launch or a browser page does not come up.