sway-session

View all files

Activity

Contributors

README

sway-session

Native Entire source uses the repository-owned Dagu pipeline for verification, security scanning and Linux package builds. Project workflow definitions live in .dagu/; shared worker infrastructure is managed separately.

sway-session — persistent workspaces for the Sway compositor

sway-session brings your registered terminals and desktop applications back when Sway starts, with their saved workspaces and window layout. Terminals use Herdr to keep sessions and pane history. Desktop applications handle their own tabs, documents, and other internal state.

It runs on Linux with Sway. Persistent terminals require Herdr and either Alacritty or Foot. Ordinary desktop-entry launches use gio; registered administrative starters use their pinned system helper directly. Flatpak applications also require flatpak.

Install

Download a package or archive from the download site, or install the Arch Linux package from the AUR:

yay -S sway-session

Previously published downloads also remain on the original release site and GitHub releases.

From v0.11.0, the public Go module identity is go.izoone.com/sway-session. Install the command with Go 1.26.10 or newer using the standard Go proxy and checksum database:

go install go.izoone.com/sway-session/cmd/sway-session@latest

This installs the executable only. Packages and make install also install completion files and integration templates.

To build from source, use Go 1.26.10, matching go.mod. Install the Entire CLI with its git-remote-entire helper on PATH and configure repository read access. Clone the canonical native source in Frankfurt:

git clone --single-branch --no-tags --branch main \
  entire://aws-eu-central-1.entire.io/et/marang/sway-session
cd sway-session
make verify
make install

Source installs put the executable in ~/.local/bin, completion files in ~/.local/share, and integration templates in ~/.local/share/doc/sway-session. Packages install the templates under /usr/share/doc/sway-session. Make sure the executable is on your PATH.

Set up Sway and Herdr

For local persistent terminals, enable pane history in your Herdr configuration (~/.config/herdr/config.toml, or under $XDG_CONFIG_HOME):

[experimental]
pane_history = true

You can also use the supplied Herdr template. Keep Herdr configuration and history private: terminal output can contain tokens and other sensitive information.

Create the configuration directory, then run Doctor inside Sway:

mkdir -p ~/.config/sway/config.d
sway-session doctor

If your Sway configuration is elsewhere, create config.d next to its main configuration file. In Doctor, select the Sway integration check and press f. Choose whether to add terminal shortcuts, review the file changes, then press y to apply them. Escape cancels. Doctor backs up files it changes. Keep only one copy of the sway-session startup commands and includes.

For noninteractive setup, preview the changes first, then apply them:

sway-session doctor --fix sway.integration --adopt-standard
sway-session doctor --fix sway.integration --adopt-standard --yes

Doctor writes config.d/50-sway-session-doctor.conf and adds its include to your Sway configuration. For a different main file, add --sway-config /absolute/path/to/sway/config. To include the standard terminal shortcuts, add --shortcuts default; define $mod before the include and free $mod+Return and $mod+Shift+Return first.

For manual setup, add these lines to your Sway configuration:

exec --no-startup-id /usr/bin/sway-session daemon
exec --no-startup-id /usr/bin/sway-session restore

For a source install, use $HOME/.local/bin/sway-session in place of /usr/bin/sway-session. The supplied Sway template also includes optional terminal bindings. Packages install it as /usr/share/doc/sway-session/50-sway-session.conf; source installs use ~/.local/share/doc/sway-session/50-sway-session.conf. Use one setup method.

Reloading Sway activates new bindings. The startup commands run at your next Sway login. To use them in the current session, start sway-session daemon in a terminal and run sway-session restore when you want saved windows restored. Keep startup commands as exec: exec_always would run them on every reload.

Terminals

sway-session terminal --new
sway-session terminal --project my-project --cwd "$PWD"
sway-session terminal --new --role codex --role shell
sway-session terminal --ephemeral --cwd "$PWD"
sway-session terminal manage
  • --new creates a separate persistent session each time.
  • --project NAME opens or focuses the same named session on later calls.
  • With no identity option, terminal reuses one default session.
  • --role codex --role shell creates a Codex-and-shell workspace in a fresh Herdr session. Existing occupied panes are left as they are.
  • --ephemeral opens a terminal without saving it for restore.

The terminal manager shows saved sessions, open windows, Herdr activity, and what will return at the next login. Its main controls are:

KeyAction
↑/↓ or j/kSelect a session
EnterOpen or focus it
/Filter
eRename
aArchive or activate
tRetry a failed restore
dPreview deletion
rRefresh

Closing a terminal during normal use archives it after a short grace period, so it stops returning at login. Its Herdr session and background agents remain. To reopen it, activate it with a, then press Enter. A terminal crash can also cause archival; the saved session is still available.

Shutdown, Sway logout, and uncertain observations preserve restore eligibility. Automatic close detection needs working logind shutdown protection. Without it, archive sessions explicitly with a.

For command-line management:

sway-session terminal list
sway-session terminal rename --label "Release work" CONTEXT_UUID
sway-session archive CONTEXT_UUID
sway-session activate CONTEXT_UUID
sway-session terminal cleanup --archived-before 2026-09-01

Cleanup previews archived sessions. To delete one, review sway-session purge CONTEXT_UUID, then repeat with --yes and the exact UUID. Purging stops and deletes the Herdr session, including its history and running work. Archiving keeps it.

Herdr remote work

Bind a persistent terminal to an exact remote Herdr session, either directly or through an existing saved Machine:

sway-session terminal --project remote-work --remote workbox --remote-session agents --cwd "$HOME"
herdr machine list --json
sway-session terminal --new --machine PROFILE_ID --label "Remote agents"
sway-session terminal --context CONTEXT_UUID

--cwd is a local launch directory; remote shells keep their Herdr-owned paths. Use an SSH alias, user@host or ssh://user@host:port for --remote and always supply --remote-session. --machine accepts an exact profile ID or unique case-sensitive label and pins its ID, target and remote session. Profile renames are fine; missing, disabled or retargeted profiles require explicit correction or a new context. These options require --new or --project; reopen by the returned context UUID or repeat the same project and remote options.

Both routes attach directly to the saved target, independent of Herdr's shared machine selection. Multiple contexts may intentionally show the same remote session. Herdr owns SSH authentication, connection handling and remote server startup. Missing/incompatible installations may produce Herdr's interactive setup confirmation; sway-session never answers it or supplies credentials.

The manager shows the remote route separately from the local window. Remote session/agent health remains unknown in this first version; a mapped window is not proof of connectivity. The global doctor still checks local pane-history setup; remote attach itself does not require local history. --role initialization and local agent reporting are unsupported for remote contexts. Manage the remote panes inside Herdr.

A closed remote window preserves restore eligibility because network failure can also close its frontend. Use the manager's archive action (a) to stop it returning at login. After archiving and closing its window, use sway-session terminal forget --yes CONTEXT_UUID to remove the registration (within Sway, or with --socket PATH). Remote purge is refused; remote work and saved profiles remain Herdr-owned. Ordinary local terminals retain their existing close/archive rules.

The original assessment records the earlier global-selection behavior. The binding contract records the implementation and downgrade boundary: older strict readers reject remote contexts; remove those registrations with the newer binary before downgrading.

Named work environments

In sway-session terminal manage, press Tab to switch to environments. An environment groups references to existing terminals and registered applications; the same context can belong to several environments.

Use n to create an empty environment, e to rename it and v to edit its members. In Members, a adds an existing context, d removes a reference and p sets the selected member as primary. Each action saves individually. Deleting an environment leaves its contexts and windows alone.

Enter runs Reach: focus the primary's existing window where it is. p previews each member's outcome; o chooses a primary for this action without changing the saved definition. Existing windows stay on their current workspaces. Missing windows are deferred with a reason because a delayed launch cannot currently guarantee preserving later user focus. Open them separately through their existing per-context action. Archived, ambiguous, hidden or unavailable primary members do not get an automatic substitute.

Saved environments remain editable offline. Reach requires Sway and a daemon running the updated binary; an older running daemon needs its normal explicit restart. See the environment design and limitations.

Restore

sway-session restore --preview
sway-session restore
sway-session restore CONTEXT_UUID
sway-session restore-report
sway-session restore-report --retry CONTEXT_UUID

The preview shows which terminals and applications are eligible for the next login without launching anything. restore opens eligible saved contexts; giving a context selects it explicitly. The daemon restores workspace placement and layout, so it must be running.

restore-report shows recorded attempts and explains failures or incomplete placement. After resolving the cause, retry the affected context. Archived contexts must be activated before using --retry. If an agent-pane setup fails after a terminal is registered, retry that same context or named request rather than creating another session.

Desktop applications

Focus the application window you want to save, then run:

sway-session app register-focused
sway-session app list
sway-session app status

Review the launcher approval dialog. If the dialog is unavailable, use app register-focused --yes from a trusted terminal after checking the launcher. Registration requires an unambiguous application identity.

Applications start in follow mode: they return at login if left open, and stop returning after their last window closes during normal use. Pinned applications keep returning even after you close them:

sway-session app pin CONTEXT
sway-session app unpin CONTEXT
sway-session app archive CONTEXT
sway-session app activate CONTEXT

Inspect saved applications and their restore evidence with:

sway-session app list --inventory
sway-session app status --context CONTEXT_UUID_OR_EXACT_LABEL
sway-session app status --inventory
sway-session --json app list --inventory

Bare app list keeps its saved registration output. Bare app status keeps reporting the focused application's registration; --inventory explains that focused application and still requires Sway. --context explicitly selects a saved application, including archived or closed contexts. Inventory list and context selection work offline, with unavailable observations reported as unknown. Add --socket PATH to select the observation socket; list requires --inventory with this option.

Inventory separates next-login policy, observed window presence, launcher validation, and recorded restore outcomes. Closed desired-open state differs from an observed absent window. Ambiguous groups never select an anchor. Launcher validity reflects current shared validation and, for Flatpak, an installation probe; it does not guarantee a successful launch. Recorded launch guards prevent duplicate attempts conservatively and do not prove a pending process. Pending automatic and explicit attempts retain their proof stages; a mapped window alone does not prove placement or layout completion. Saved placement-only layout and recorded layout failures explain fidelity limits.

These commands do not launch applications, approve launchers, repair state or assess whether the daemon can launch immediately. They read one saved-state snapshot before optional observations, which share a three-second deadline. The opt-in JSON envelope includes applications and an empty contexts array. It omits approved launcher paths, arguments, environment and compositor socket identity, while retaining labels and workspace placement as operational data.

Use app rebind-focused CONTEXT to associate a replacement window, or app reapprove CONTEXT after an approved launcher or executable changes. app forget --yes CONTEXT_UUID removes the registration.

sway-session saves the application's outer window placement. For applications with several indistinguishable windows, it avoids choosing a window to move. The application decides which tabs, files, profiles, or URLs reopen.

To keep a registered application in the scratchpad, register it on a normal workspace first, then move it to the scratchpad as usual. Its saved anchor returns hidden or shown on its saved workspace. Scratchpad cycling order and additional application windows may differ after restore.

Administrative desktop starters

Register administrative applications through the same commands as other apps:

sway-session app register-focused
sway-session app reapprove CONTEXT

The normal confirmation explains when restore may request system authentication. register-workspace, rebind-focused and the usual --yes path work the same way. The saved Follow/Pinned policy may restore the unchanged approved starter at login and request normal authentication, without another sway-session confirmation. Acceptance or uncertainty, including a dismissed authentication dialog, retains a duplicate-launch guard for that compositor lifetime through daemon restarts. A new compositor may try again when the saved policy is eligible.

Supported desktop Exec forms use /usr/bin/pkexec PAYLOAD or /usr/bin/sudo [-A|--askpass] PAYLOAD, with an absolute, direct, root-owned payload. Bare pkexec/sudo are explicit shorthand for those canonical /usr/bin helpers, without PATH lookup. The existing persistent daemon starts the pinned helper directly; ordinary desktop entries still use GIO. Both executables must be regular nonsymlink files under trusted root-owned paths. Terminal/D-Bus routes, a nonempty desktop Path working directory, custom users, environment wrappers, shells and indirect payloads remain unsupported. sudo's existing policy, cache or askpass setup owns authentication; a TTY-only setup is not made usable and sway-session supplies no new askpass mechanism or password transport.

Approval pins the full desktop file and both executable contents, even for system entries. Changes require app reapprove CONTEXT again. Inventory marks administrative registrations without claiming authentication status. Process-start acceptance and mapping_timeout cannot establish whether authentication succeeded or was cancelled. If the daemon exits, pending pkexec authentication may be cancelled; continuous authentication or application survival is not guaranteed. sway-session collects no credentials and never kills possibly accepted work to undo an uncertain result. Arguments come only from the approved desktop file through bounded field-code expansion, with no file/URI launch inputs; unsupported field forms require correcting and reapproving the entry. Literal # characters must be quoted or escaped; administrative Exec comments are unsupported.

Older binaries reject these registrations even when archived. Before downgrade, use the newer binary to forget them or restore a private pre-feature backup; never mix writer versions. See the administrative restore decision for the scope and trade-off.

Configuration and command help

The default terminal is Alacritty. To use Foot, create ~/.config/sway-session/config.toml (or under $XDG_CONFIG_HOME); linked dotfiles and configuration directories are supported:

version = 2

[terminal]
adapter = "foot"
session_manager = "herdr"

The supported adapters are alacritty and foot; the session manager is herdr. Bash, Zsh, and Fish completion files are included with the installation.

Use sway-session --help for the command list and sway-session help COMMAND for options, for example sway-session help app. Global options precede the command: sway-session --json terminal list or sway-session --config /path/to/config.toml terminal --new. sway-session --version identifies the installed build.

State backup and recovery

State is stored under ~/.local/state/sway-session, or $XDG_STATE_HOME/sway-session. Backups contain sway-session registration, environment definitions and layout metadata. Back up Herdr history, application data, approved desktop launchers, and configuration separately.

install -d -m 0700 "$HOME/sway-session-backups"
sway-session state backup --output "$HOME/sway-session-backups/before-change.sqlite3"
sway-session state recover --from "$HOME/sway-session-backups/before-change.sqlite3"

Use a new backup filename. Recovery previews by default; inspect it before applying. Use clean absolute paths, with an owner-only 0600 backup file in a 0700 directory owned by your user. Use state backup instead of copying a live database file.

Use the updated binary for backups containing environments: older binaries' strict validators can reject the new tables. Keep a pre-upgrade backup if you need to downgrade. Recovery replaces metadata rather than merging it; see the environment compatibility notes.

Before applying, stop the daemon and all other sway-session processes, including standalone brokers. Recovery requires a valid XDG_RUNTIME_DIR and refuses busy state. Then run:

sway-session state recover --from "$HOME/sway-session-backups/before-change.sqlite3" --yes

Recovery reports where it retained previous state. If interrupted, preserve the source and repeat the same command to resume. An error can follow a partial replacement: inspect the reported result and artifact paths before restarting the daemon. See recovery details.

Troubleshooting

Run sway-session doctor for setup checks and repair previews, or sway-session doctor --check for a noninteractive report. Doctor does not start the daemon or reload Sway for you.

If windows do not return, check restore --preview for archive policy and restore-report for launch and placement results. If Doctor reports a daemon build mismatch after an upgrade, follow its stop/start instructions.

For an interrupted registration, rebind, or purge, run sway-session state operations and follow the operation recovery guide.

Further documentation

For development, run make fmt and make verify. Live compositor tests use disposable state and workspace 98 or higher; see the verification guide.