Deploying to Your Team

For rolling Swarmfile out to a fleet rather than having each person install it by hand - silent install, GPO/MDM push, and what a freshly-provisioned machine needs (or doesn't) before someone signs in.

Windows#

Prerequisites first, then the app#

The download most people should use is the bundled installer (Swarmfile-Setup.exe / Swarmfile-x64-Setup.exe), which chains WinFsp, the VC++ Redistributable, and WebView2 ahead of the app itself, skipping anything already present. For a scripted fleet rollout, install those prerequisites through your own tooling (GPO, SCCM, Intune) first, then push the bare .msi - it's published under its own stable name specifically for this, and unlike the bundle it does not install those prerequisites itself:

msiexec /i Swarmfile-x64.msi /qn /norestart

/qn (fully silent) and /norestart are the same flags this project's own CI uses to verify the installer end to end, not a guess - that's a meaningfully stronger guarantee than "should work" for an MSI. Uninstall is the mirror image: msiexec /x <ProductCode> /qn /norestart.

The app install itself doesn't require a reboot - it closes and relaunches Explorer to pick up the shell integration, not the OS.

It installs per-machine, which is what makes GPO work#

The MSI installs per-machine (not per-user), so a Computer Configuration software-installation policy is the right kind of GPO push - you don't need a per-user policy for it to reach everyone who logs into that machine. Auto-launch for the tray and engine is likewise registered machine-wide, so every user account on a pushed machine gets Swarmfile running automatically at login, not just whichever account happened to run the installer.

There's no way around this today: an employee's first launch requires them to sign in through the tray - a browser-based flow (password grant, or your SSO's login page via PKCE). Nothing in the product supports a fully unattended, no-user-interaction first login for a regular desktop seat. If you need machines that never have a human sign in - a render farm node, a CI runner, a headless seed node - that's a different mechanism entirely: see Headless and service machines below.

What is automatic: once someone signs in, the engine adopts their org and project on its own whenever the answer is unambiguous - specifically, when the account belongs to exactly one org, and that org has either a single project or one named default. For a typical single-project team this means zero manual setup after sign-in. For an org with several projects and no default-slugged one - the more likely shape for an org that IT provisioned directly rather than one that went through self-serve signup - a newly-provisioned employee's engine will still pick up the right org automatically, but will land with no project selected, and they'll need to choose one in the tray's org/project picker. Worth knowing before you tell people "just sign in and it works" - for most orgs it will, but not guaranteed for every org shape.

If your team is provisioned via SCIM or SSO (see Identity), that removes the manual-invite step entirely - an employee who's in your IdP can sign in the moment their machine has Swarmfile installed, with no separate Swarmfile-side invite to send.

If you're self-hosting the control plane#

Everything above assumes the standard hosted service, where a fresh install already knows which hub and identity provider to talk to. If you're on the Enterprise self-hosted control plane, that needs to be told which hub and identity server are yours before first launch - pre-stage a config.json next to the install with your hub_url, oidc_issuer, and oidc_client_id set, and push that file alongside the installer through the same GPO/MDM channel. See Engine Config File for the full key reference.

macOS#

The installer is a single signed and notarized universal .pkg (Intel and Apple Silicon). Standard MDM package-deployment tooling (Jamf, Kandji, Mosyle, Apple Business Manager) should work with it - the installer's own setup step is written to recognize when it's running under an MDM-driven install session rather than a human at the keyboard, and logs accordingly so it shows up sensibly in your MDM's policy logs rather than as a silent failure. That said, we haven't validated a specific Jamf/Kandji policy template end to end - if you hit something MDM-specific that doesn't behave the way you'd expect, let us know rather than assuming it's expected behavior.

Linux#

The .deb pulls its one real dependency (libfuse2) in automatically through normal apt/dpkg dependency resolution - nothing extra to stage. It enables the engine and tray as per-user systemd units globally, so new logins pick them up with no further action; a user already logged in at install time won't have them start automatically until their next login (or you start them by hand). The tray unit is conditioned on a graphical session and quietly does nothing on a headless box, which is the correct behavior for a Linux seed/NAS node.

One thing the package does not handle: some distributions require /etc/fuse.conf's user_allow_other set, or the installing user added to a fuse/plugdev group, before a non-root user can mount via FUSE. If mounting fails with a permissions error on a specific distro, check that first - it's a FUSE/distro configuration matter, not something the .deb sets up for you.

Headless and service machines#

Render-farm nodes, CI runners, and self-hosted seed nodes don't have anyone signing in interactively, so they use a different credential entirely: a project-scoped API key (swarmfile api-key create <name> --project <id>, admin/owner-only), set as SWARMFILE_API_KEY on the target machine. An engine started with that env var skips the browser sign-in flow completely - no human interaction, ever - but is confined to exactly the one project the key was minted for. This is the right tool for provisioning unattended fleet machines as part of a rollout; it's a separate concern from getting Swarmfile onto employees' desktops, and the two shouldn't be conflated - a desktop seat always goes through interactive sign-in (above), a service machine never does.

Repairing or reinstalling at scale#

swarmfile-doctor --repair --yes is built for exactly this - the --yes flag exists specifically so it can run non-interactively from MDM/SCCM/Ansible. It still needs to run with the same elevated privileges an interactive install would (SYSTEM on Windows, root on macOS/Linux) - a scripted push job running as SYSTEM/root can drive it directly; it's not something you can trigger remotely from an unprivileged context. See swarmfile-doctor.

Where to go next#

Identity - set up SSO and SCIM before you push installers, so first sign-in is zero-touch for provisioned employees.
Network Requirements - the firewall allowlist to have in place before rollout.
Engine Config File - every config.json key, for self-hosted or otherwise customized deployments.
Self-Hosted Seed Nodes - turning existing on-prem hardware into a warm cache tier as part of the same rollout.