swarmfile-runner
swarmfile-runner runs the engine in runner mode: it sets SWARMFILE_RUNNER_MODE=true (when the variable isn't already set), then re-execs the sibling swarmfile-engine binary with the same arguments and standard I/O. It has no subcommands or flags of its own - every engine flag passes straight through - and it runs the real engine boot path (config, single-instance lock, lifecycle) exactly as SWARMFILE_RUNNER_MODE=true swarmfile-engine would.
It exists so the headless CI role reads as its own tool rather than "the engine with an env var". For what a runner does and how to wire it into a CI system, see Runner (Headless CI).
Because it re-execs the engine, swarmfile-runner --help is the engine's help. The pass-through flags:
| Flag | What it does |
|---|---|
--build-info | Print the enabled cargo features and target architecture, then exit. |
--status | Engine, hub, peers, and pending work at a glance (works while another engine holds the lock). |
--capabilities | The compiled feature set of this binary. |
--print-env-vars | The resolved SWARMFILE_* values this build consumed, secrets redacted. |
--pause / --resume | Pause or resume sync on a running engine without unmounting. |
--quit | Ask the running engine to drain and stop. |
--pin / --unpin / --list-pins / --verify-pins | Offline cache pins: add, release, list, and verify. |
--prepare-offline [SECS] / --return-from-offline | The engine-level Pack & Go pair - see Working Offline. |
See Engine Config File → Engine command-line flags for the full descriptions.
Environment#
| Variable | Description |
|---|---|
SWARMFILE_RUNNER_MODE | Forced to true when unset. An explicit value is preserved, so SWARMFILE_RUNNER_MODE=false swarmfile-runner still runs in normal mode |
SWARMFILE_API_KEY | Project API key the runner authenticates as |
SWARMFILE_PROJECT_ID | Project the runner serves |
SWARMFILE_BRANCH | Branch the runner tracks (defaults to the project's main) |
Runner mode deliberately serves no control socket. A driverless CI host needs no FUSE - materialize and runner mode never call the mount path.
Acquiring it#
- Linux - the
.debinstalls it at/usr/bin/swarmfile-runner, next toswarmfile-engine(the Docker output carries it too; ask us about an.rpm). - macOS - it ships inside
Swarmfile.app/Contents/MacOS/swarmfile-runner, next to the bundled engine, with a/usr/local/bin/swarmfile-runnersymlink on a prod install. - Windows - the MSI installs it next to
swarmfile-engine.exein the install folder, and the app-only zip carries it. - Anywhere else - build it from source:
cargo build --release -p swarmfile-engine --bin swarmfile-runner. It must sit in the same directory asswarmfile-engine, because it re-execs the sibling resolved next to its own executable. - Equivalent without the alias - on any engine binary,
SWARMFILE_RUNNER_MODE=true swarmfile-enginebehaves identically.
Example#
SWARMFILE_API_KEY=sf_key_... SWARMFILE_PROJECT_ID=proj_xyz789 swarmfile-runner
Because it re-execs the engine, the process's exit code and output are the engine's. If the sibling swarmfile-engine is missing, the alias prints an error and exits 127.