Swarm docs

Everything you need to run Swarm: the app, its daemon, and the command line.

Install

Download Swarm-0.1.0.dmg. It's a universal app for Apple silicon and Intel and needs macOS 13 Ventura or later.
Open the DMG and drag Swarm.app to Applications.
This early build isn't notarized yet, so macOS blocks the first launch. Open System Settings → Privacy & Security, scroll down and click Open Anyway.

To use swarmctl from any terminal, link it onto your PATH:

ln -s /Applications/Swarm.app/Contents/MacOS/swarmctl /usr/local/bin/swarmctl

Sessions and tabs

Every tab is a session: a shell owned by Swarm's daemon, swarmd, not by the window. Closing a tab detaches it; the session keeps running and waits in the sidebar's detached list until you reopen it. To end a session for good, choose Terminate from its menu, or runswarmctl rm.

Quitting the app leaves every session running. When it starts again, it reopens the tabs you had open.
Reopened tabs show their earlier output, including blocks, exit codes and durations.
Splitting a pane starts a new session, so each pane can be detached and reattached on its own.

Remote hosts

Click Connect… in the sidebar and pick a host from your ~/.ssh/config, or typeuser@host[:port]. Swarm connects with your own ssh setup (keys, agent, jump hosts) and installsswarmd on the host if it isn't there. Hosts can run Linux or macOS.

Remote sessions live on the host. If your laptop sleeps or the network drops, the tabs show that they're reconnecting and pick up where they were.

Scrollback

Each session keeps its last 16 MB of output in memory, and all sessions together are capped at 512 MB; the idlest sessions are trimmed first. Nothing is written to disk by default.

To keep more, turn on Settings → Daemon → Keep scrollback beyond 16 MB on disk, or runswarmd spill on. Output that leaves memory is then saved encrypted, up to 256 MB per session by default (--limit-mb N changes it). The key exists only in that session's process, and the files are deleted when the session ends or the setting is turned off.

$ swarmctl dump build > build.log      # all kept output, as text
$ swarmctl dump build --raw            # with escape codes

swarmctl

The command-line client sees the same sessions as the app. Add --host <ssh-host> to any command to talk to that host's daemon instead.

`swarmctl ls`	List sessions with their state, folder and last activity.
`swarmctl new -n build`	Create a session and attach to it (`-d` to leave it detached).
`swarmctl attach build`	Attach by id, id prefix or name. Ctrl-\ detaches.
`swarmctl rename build ci`	Rename a session; the app follows live.
`swarmctl dump build`	Print everything the session has kept.
`swarmctl info build`	Show everything known about a session.
`swarmctl kill build`	Send a signal to the session's process (HUP by default).
`swarmctl rm build`	End the session if needed and drop it.

The daemon

swarmd starts with the app by default. To have sessions survive logout and start the daemon at login instead (a launchd agent on macOS, a systemd user unit on Linux):

$ swarmctl daemon install-service

swarmctl daemon uninstall-service goes back to starting on demand. swarmctl daemon stopstops the daemon without ending any session. When a new version starts, running sessions move to it in place;swarmctl daemon upgrade-shims does that by hand.

Troubleshooting

macOS says Swarm can't be opened: Allow it once in System Settings → Privacy & Security → Open Anyway. Notarized builds are coming.
A remote tab keeps reconnecting: Check that ssh <host> works without a password prompt from a terminal; Swarm uses the same configuration.
A session I closed is gone from the tabs: It's detached, not ended. Open it from the detached list in the sidebar, or run swarmctl ls.