Persistent sessions

By default, toowld owns every PTY directly: if the daemon restarts, your running sessions end with it. Persistent sessions moves each session into a tiny custodian process so the PTY survives a daemon restart. Re-connect after the daemon comes back and your shell is exactly where you left it.

Enabling persistent sessions

Set the environment variable TOOWLD_PERSISTENT_SESSIONS=1 in the daemon's environment before it starts. The flag is off by default.

If you run toowld under systemd, add an Environment= line to the unit:

[Service]
Environment=TOOWLD_PERSISTENT_SESSIONS=1
ExecStart=/usr/local/bin/toowld

If you start the daemon manually from a shell, export it before launching:

TOOWLD_PERSISTENT_SESSIONS=1 toowld

Restart the daemon for the change to take effect. Sessions created afterwards will be persistent; sessions already running before the restart are not retroactively enrolled.

How it works

When a new session is created with the flag set, toowld forks a custodian — a second copy of the toowld binary running in --custodian mode. The custodian owns the PTY and the scrollback ring and keeps them alive independently. The daemon holds only a lightweight reference. When toowld restarts, it scans for running custodians on the local socket namespace and reattaches to any it finds, making those sessions immediately available to the next client that connects.

What it does and does not survive

For a record that does survive reboots, use the transcript export: any session can export an asciinema .cast file via the ExportCast capability. That file persists on disk across reboots and can be replayed or archived.

With the TUI client

Persistent sessions compose naturally with the TUI's auto-reconnect (introduced in Phase 8). If toowld restarts while you have a TUI client open, the client shows a brief reconnecting… banner, then reattaches. Combined with persistent sessions, this means your shell — including any long-running process inside it — is uninterrupted. This is particularly useful for agentic coding tasks that run for hours on a remote server: a daemon upgrade or accidental restart no longer drops the session.

Checking session status

List sessions and their custodian state with:

toowl ls

Persistent sessions show a P flag in the status column. toowld doctor also reports whether the flag is active for the running daemon.

Keep going

• TUI client — the crossterm client that benefits most from persistent sessions.
• Workspaces — named windows that survive disconnects independently of this flag.
• Remote machines — attach to a remote daemon from the GUI or TUI.