Architecture
Enough detail to judge whether the design is sound, without a tour of the source tree.
The shape
Section titled “The shape”The host agent
Section titled “The host agent”One process per host owns everything: session records, board layout, workspace list, device registry, notification routing, and supervision of the tmux sessions.
Clients are deliberately thin. They render host state and send input. This is why two devices showing the same session cannot disagree — there is only one copy of the truth, and it is not on either of them.
The RPC channel
Section titled “The RPC channel”All clients talk to the host over an SSH-backed RPC channel — including the macOS app talking to a host on the same machine.
There is no localhost fast path. That is a design rule, not an oversight: a special case for the most-used configuration would be the one code path with its own bugs, exercised most and tested least. Localhost gets the same architecture as a VPS in another country, so a fix for one is a fix for both.
The transport underneath can be your local network, Tailscale or the relay. See How your devices reach your host.
Sessions in tmux
Section titled “Sessions in tmux”Every session runs in tmux, on its own socket, with Offsite’s own config
file. Offsite never touches your ~/.tmux.conf and never requires tmux plugins.
tmux is what makes a session outlive the app, the network and the host agent itself: updating the host restarts the agent, and the sessions do not notice.
Restore after reboot is owned by Offsite’s own session state plus each CLI’s
resume mechanism — never by global tmux tooling like tmux-resurrect.
Host state lives in ~/.offsite: a SQLite database for session and board state,
JSON files for workspaces, devices and settings, and directories for uploads,
session archives and helper installs. See
What Offsite puts on your machine.
What this buys you
Section titled “What this buys you”| Property | Because |
|---|---|
| Sessions survive everything | they belong to host-owned tmux, not to a client |
| Devices never disagree | one authoritative state, on the host |
| No vendor in your loop | the CLIs call your provider directly |
| Localhost is not a special case | one connection architecture for every host |
| Your tmux stays yours | Offsite-owned sockets and config, always |
What we do not detail here
Section titled “What we do not detail here”Sync and revision semantics, the rendering and snapshot pipeline, connection racing heuristics and the notification state machine are deliberately out of scope. They are the parts most likely to change, and knowing them does not help you decide whether Offsite fits your work.
Details
Section titled “Details”- Host and clients negotiate a protocol version, with a documented minimum on both sides. See Updating Offsite.
- Compatibility policy: additive fields only unless the protocol version changes; host state migrates forward; a schema mismatch must never silently delete data; destructive resets are explicit user actions.
- Notifications are driven by CLI hook events reported back to the host, not by reading the screen.
- The macOS app bundles Chromium (CEF) for browser cards; third-party sign-in popups do not work reliably in WKWebView.
- Host components are published per version and pulled over HTTPS from
get.offsite.sh.