sway-session
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 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
--newcreates a separate persistent session each time.--project NAMEopens or focuses the same named session on later calls.- With no identity option,
terminalreuses one default session. --role codex --role shellcreates a Codex-and-shell workspace in a fresh Herdr session. Existing occupied panes are left as they are.--ephemeralopens 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:
| Key | Action |
|---|---|
| ↑/↓ or j/k | Select a session |
| Enter | Open or focus it |
/ | Filter |
e | Rename |
a | Archive or activate |
t | Retry a failed restore |
d | Preview deletion |
r | Refresh |
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
- Agent hooks and session reporting
- Optional AppArmor hardening and security limitations
- Architecture
- Verification and live testing
- Contributor workflow and releasing
For development, run make fmt and make verify. Live compositor tests use
disposable state and workspace 98 or higher; see the verification guide.
