Sessions and why they survive

A session is one long-running program on a host, shown to you as a card. It can be an agent CLI, a plain shell, a browser target or a mirrored Simulator.

The important part is where it lives. A session belongs to the host, not to the app you are looking at it with. Offsite starts it inside tmux on the host machine and then streams that terminal to every device you have connected.

Close the app on every device and the session keeps running on the host; open it again and you are back in the same terminal.

What does not stop a session

• Closing the app, on any device
• Losing Wi-Fi, switching networks, going through a tunnel
• Putting your client to sleep
• Putting the host to sleep (it continues on wake — see Keep the host awake if you would rather it did not sleep)
• Updating the host components

What does stop one

• Ending it yourself (End Session)
• The program exiting on its own
• The host machine powering off — and even then, see below

After a host reboot

Offsite recreates the tmux session and then resumes the conversation using each CLI’s own mechanism: claude --resume, codex resume, wired in per tool. You come back to the agent’s history, not to a fresh prompt.

The restore starts as soon as one of your devices connects. Codex, Grok and terminal sessions come back right away. Claude Code on a Mac host waits until someone signs in on the Mac, because its sign-in lives in the login keychain; the apps show Waiting for Mac login to restore N sessions…, and a Claude card lets you unlock the keychain from your device. For a host that comes back before anyone logs in at all, turn on Always on.

After a restart, Codex, Grok and terminal sessions come back when a device connects, and Claude Code on a Mac host follows once the Mac's login keychain is unlocked.

To make that reliable, Offsite keeps its own archive copy of the resume artefacts, so a transcript cleanup on the CLI’s side cannot orphan your session.

What the card shows after the resume is the agent’s current context window: the summary from its last compaction and everything since. The full transcript stays on disk; see Troubleshooting.

Session states

The card shows what a session is doing:

Session states

1. a turn is runningWorking
2. the agent finishes or asks
3. Needs attentionfinished a turn, or waits for youNeeds inputnotification
4. you look at the card
5. ready, last turn seenReady
6. you send a prompt

A turn runs, ends with the card asking for you, and settles to ready once you have seen it.

On the card	Meaning	In the Icebox and Archive
a spinner	a turn is running	Working
Needs attention	the agent finished a turn or waits for you: a permission prompt, a question	Needs input
neither	ready at the prompt, and you have seen its last turn	Ready

These drive notifications too.

Details

• Each Offsite session runs on its own tmux socket (tmux -L offsite-<tool>-<session-id>) with Offsite’s own config file. Offsite never writes ~/.tmux.conf, never requires tmux plugins, and never changes your global tmux setup — a hard rule, not a default.
• Session records live in ~/.offsite/sessions/ and ~/.offsite/state.db; resume artefacts are archived to ~/.offsite/session-archives.
• Sessions receive OFFSITE_SESSION_ID, OFFSITE_WORKSPACE_ID, OFFSITE_TOOL and OFFSITE_SESSION_KIND in their environment.
• Agent CLIs run in their fullscreen (alternate-screen) mode, which is why the card has no scrollback to search — the CLI owns the viewport and manages its own history.
• Scrollback limit for shell sessions is set on Offsite’s own tmux config, not on yours.