User guide / Workspaces and persistent sessions

Managing sessions from the command line

Development reference · View source

runyte --mux [WORKSPACE]                # or runyte -a [WORKSPACE]
runyte --session-stop [WORKSPACE]       # or runyte -s [WORKSPACE]
runyte --session-restart [WORKSPACE]
runyte --session-rename WORKSPACE NAME
runyte --session-list                   # or runyte -l
runyte --session-list --include-hidden
runyte --session-stop-all
runyte --session-stop-all --include-hidden
runyte --session-clean

Omitting WORKSPACE from attach, stop, or restart selects the project found from the current directory.

Selecting a session

WORKSPACE may be:

  • the abbreviated ID a listing shows, any other unambiguous ID prefix, or the full ID;
  • the exact session name;
  • the project directory.

IDs are stable hashes of canonical project directories, shown abbreviated to six characters. A listing lengthens them only when two of its own rows would otherwise match, so the ID shown always selects that row.

Names:

  • A project is named after its directory when first recorded. A taken name gets the first free suffix from -2: three runyte directories become runyte, runyte-2, and runyte-3. Unnamed history entries get defaults on the next listing.
  • runyte --session-rename WORKSPACE NAME renames a running session (through its host) or a stopped one (in its history).
  • Names persist across restarts and must be unique among running sessions.
  • Surrounding spaces are trimmed and inner spaces become -: release candidate is stored as release-candidate. Default names follow the same rule.
  • Names live under the workspace state root, normally .runyte/host-names/.

Listing sessions

runyte --session-list shows running and recently visited sessions with ID, NAME, DIRECTORY, STATE, UNSAVED, TERMINALS, WAITING, JOBS, ACTIVITIES, and TUI columns.

  • Order matches the manager: numbered sessions in digit order, then the rest least recently visited first. With no number column, this reads as running sessions ahead of stopped ones.
  • STATE is running, stopped, or running (protocol N) for a host from another Runyte version. Such a host still holds the workspace, so nothing can attach or open files through it, and its unsaved counts are unknown.
  • It reads the Runyte environment selected by the current runtime and cache settings. --include-hidden adds validated live sessions from other isolated Runyte environments. Stopped history stays local, since there is no live host to publish it. If two environments host the same workspace, both endpoints appear with the same ID and directory.

History and names live in workspaces.json in Runyte’s platform cache directory: $XDG_CACHE_HOME/runyte when set, else ~/.cache/runyte on Linux or ~/Library/Caches/runyte on macOS. Without the XDG override, Unix takes the home directory from the effective operating-system account, not $HOME, so a privileged launch cannot create its cache as root in another account’s home. Because this is per-user cache rather than the runtime registry, stopped projects stay listed across logout.

Stopping and restarting

Protected state. Stop and restart refuse while the host owns:

  • unsaved buffers,
  • pending --wait requests,
  • live terminal children,
  • active plugin jobs or continuing activity leases.

The refusal names each count. Add --force to discard that state.

  • The scratch buffer never counts as unsaved: it has no path, so nothing could be saved in place. A scratchpad never keeps a workspace alive, and stopping or retiring the host discards it.
  • A normal stop never kills a host from another protocol version, since it may own live terminals or unsaved buffers. Use a compatible client, or make the loss explicit with runyte --session-stop --force.

Restart replaces the running host without attaching a TUI, and keeps its name. It does not keep clean buffers or other in-memory state. If the host used a non-default configuration, pass the same --config PATH.

--session-stop-all applies the same checks to every running session in the current environment, and continues past refusals so unrelated clean hosts still stop. --include-hidden applies it to every validated live endpoint in the owner-wide inventory, including copies of one workspace in several environments. --force makes the loss explicit for every host.

--session-clean forgets every stopped row from history after rechecking the inventory. Running sessions, workspace directories, and project files are untouched.

Idle hosts

By default a persistent host keeps running after detach, with its language servers, until stopped with :session-stop or otherwise shut down. Set workspace.idle_retirement_minutes to a positive number to retire a clean host after that many minutes without an attached client, an outstanding --wait request, or a live terminal child. The default 0 never retires.