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 mass deployment, 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

If a probe-backed prerequisite is missing, the MSI refuses during install with a message naming it - WinFsp or the VC++ Redistributable (instead of applying and failing later with a side-by-side or mount error). WebView2 is required at first launch but is not part of that gate; the bundle installs it, so stage it in the same task sequence when you use the bare MSI. The checks are Installed OR …-guarded, so repair and upgrade are never blocked by a missing prerequisite.

/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.

A scripted rollout never sees Windows' SmartScreen prompt. If someone runs a freshly downloaded Swarmfile-Setup.exe by hand, Windows shows More info → Run anyway until the signing identity builds up download reputation - expected, not a failed download. The Setup.exe/.msi are Authenticode-signed; the -bin.zip payload is not. See Getting Started.

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 Desktop App 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. It also installs the command-line tools (swarmfile, swarmfile-lfs, swarmfile-doctor, swarmfile-migrate, swarmfile-search, swarmfile-verify-history, swarmfile-seed, swarmfile-runner, git-remote-swarmfile) into C:\Program Files\Swarmfile and appends that folder to the machine PATH, so a pushed machine gets the CLI with no per-user setup.

The MSI also adds an inbound Windows Firewall rule for the engine: UDP, local subnet only, Domain and Private profiles. Without it, a silently installed machine can't discover or be reached by colleagues' machines on the office LAN, and every transfer goes through the cloud. The rule is removed on uninstall. If your GPO ignores locally added firewall rules, push the equivalent rule yourself. See Network Requirements for the exact rule and a New-NetFirewallRule command.

First sign-in is still interactive#

There's no way around this today: an employee's first launch requires them to sign in through the Desktop App. For password sign-in, that's a plain email/password form inside the Desktop App itself - no browser involved at all. For SSO, it's a real browser-based flow: the Desktop App hands off to your system's default browser for the IdP's login page via PKCE, then returns control to the Desktop App. Nothing in the product supports a fully unattended, no-user-interaction first login for a regular desktop seat, regardless of which method you use. 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 an org and project on its own, and it's more permissive than you might expect - it doesn't wait for an unambiguous single choice. It picks the first org the account can reach (even for a multi-org account - there's no picker on first run), and within that org it picks the default-slugged project if one exists, else just the first project in the org. Orgs start with zero projects: creating the first one is a deliberate action in the dashboard (or swarmfile project create), and until an org has one there is nothing for the drive to mount. Once every org you're rolling out has a project, "just sign in and it works" is accurate for nearly every org shape - the drive mounts to some project on first launch, not necessarily the one you'd have picked for them. If a newly-provisioned employee needs a specific non-default project, that's a one-click switch in the Desktop App's org/project picker after first sign-in, not something to pre-plan around. The same switch is scriptable without the Desktop App - swarmfile workspace list, then swarmfile workspace switch --org <id> [--project <id>] - and, like the picker, it needs no re-authentication: the session already covers every org the account can reach. See Organizations, Projects & Members.

If your org has SSO configured with an auto-provisioning group (see Identity), that removes the manual-invite step for anyone in that IdP group - they can sign in the moment their machine has Swarmfile installed, with no separate Swarmfile-side invite to send. SCIM alone doesn't do this on its own: it syncs your directory into Swarmfile, but org access still requires that SSO group match or a manual invite.

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. A self-hosted control plane - the same software running entirely on infrastructure you operate - is available on Enterprise. With it, the deployment needs to know 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, and talk to us to scope a self-hosted deployment.

macOS#

The installer is a single signed and notarized universal .pkg (Intel and Apple Silicon), built to work with standard MDM package-deployment tooling (Jamf, Kandji, Mosyle, Apple Business Manager) - its own setup step recognizes 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. If you hit anything MDM-specific that doesn't behave the way you'd expect, let us know.

Linux#

The .deb pulls its runtime dependencies (libwebkit2gtk-4.1-0, libgtk-3-0, libfuse2) in automatically through normal apt/dpkg dependency resolution - nothing extra to stage on a normal online install, though an offline or mirrored image needs all three available in the mirror. It enables the engine and Desktop App 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 Desktop App 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.

The .deb doesn't touch your firewall either. If machines run ufw or firewalld with inbound traffic denied, allow UDP from the local subnet so LAN peers can find each other. Network Requirements has ready-made rules.

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.

Self-hosted seed nodes have a guided path aimed at exactly this: Settings → Office caches generates a cache's complete seed.env for a chosen office and project (scope, hub URL, and a freshly minted project-scoped key, shown once), then lists the whole fleet with liveness and the bytes each cache served this week. Owners and admins get a weekly report email and one alert per day-long outage, both muteable under Settings → Notifications. See Self-Hosted Seed Nodes for setup and sizing.

Each key can also be given its own request ceiling (swarmfile api-key rate-limit <id> <max>, admin/owner-only), capped at the org's per-user limit - the lever for letting a fleet burst without raising a person's window. See Organizations, Projects & Members.

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 provisioned employees can sign in and start on first launch with no separate invite to send.
• 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.