Getting Started

Swarmfile mounts your team's project storage as a real local drive. It is not a sync folder - nothing downloads to your machine until you actually open a file. Browsing a folder with tens of thousands of files costs zero disk space. Opening a 200GB file streams only the bytes your app reads.

Installing the client#

Download the installer for your platform from Downloads.

macOS - a signed and notarized universal .dmg/.pkg that runs on Apple Silicon and Intel. The client uses FUSE-T, so there is no kernel extension: no Recovery-mode "Reduced Security" step, no rebooting to approve a kext, no security prompts beyond the normal Gatekeeper install.
Windows - a Setup bundle that chains the required dependencies (WinFsp, the VC++ Redistributable, and WebView2) automatically, so you don't need to install them separately. Both ARM64 and x64 builds are supported.
Linux - a .deb package (Debian/Ubuntu). Need an .rpm (Fedora/RHEL/openSUSE)? Get in touch and we'll provide one.

The .pkg, MSI, and .deb installers also put the swarmfile command line on your PATH, along with the standalone tools (swarmfile-lfs, swarmfile-doctor, swarmfile-migrate, swarmfile-search, swarmfile-verify-history, swarmfile-seed, swarmfile-runner) and the git-remote-swarmfile helper that backs git clone swarmfile:// - see CLI: swarmfile. There is no separate CLI download. On macOS, the .pkg is what installs those PATH entries: the .dmg installs the Desktop App, whose bundle carries the same tools but doesn't link them into /usr/local/bin, so a .dmg-only install needs one .pkg (or Diagnostics → Reinstall) run to put the CLI on PATH. (swarmfile-brlock is a developer reference client built from source, not part of the desktop install.)

Windows: the SmartScreen prompt#

The first time you run the downloaded installer, Windows may show a blue "Windows protected your PC" box from Microsoft Defender SmartScreen. This is expected: the Setup.exe and .msi installers are Authenticode-signed, but SmartScreen warns until the signing identity has built up download reputation, and the .zip's tools plus the standalone swarmfile-doctor download are not code-signed at all. Either way, it does not mean the download failed or was tampered with.

Click More info - the small link, not Don't run; the Run anyway button appears underneath.
Click Run anyway.
If Windows asks for permission, choose Yes, then finish the installer as usual.

You see the prompt when you run a freshly downloaded installer; automatic updates inside the app don't show it. A scripted mass deployment (msiexec, GPO/SCCM/Intune) never sees it - see Deploying to Your Team.

Signing in#

Open the client and sign in with your email and password, or with your organization's SSO if your IT team has configured an identity provider. The default form is email/password against the built-in identity provider; for SSO, click "Sign in with SSO" and enter your organization's slug (the short name in your org's Swarmfile URL) - the client looks it up and shows a "Continue with <your IdP>" button if that org has SSO configured. There's no email-domain auto-detection: you need to know your org's slug (or use the direct per-org sign-in link your admin can share) rather than just entering your email and having it figured out for you. An organization on Starter or above can also require an authenticator app, a verified email, or both before it admits members; if yours does, you're prompted to enroll before enforcement starts. If your account has an authenticator app, sign-in asks for its current six-digit code after your password (enter a recovery code instead if you don't have the app), and a wrong code can simply be retried. See Identity.

Switching to a different account while the app is running is refused (account_switch_requires_restart): the local cache identity is reconciled only at startup, so that one user's unsent work can never be uploaded as another's. Sign in with the other account and restart when the Desktop App offers it - the requested sign-in is kept, and the restart completes the switch; any unsent work from the previous account is quarantined on your machine rather than lost.

New to Swarmfile? Starter and Pro start with a 7-day free trial covering up to 2 seats (signing up past 2 seats starts paid), and a no-card Free plan covers public projects up to 1 GiB - see pricing.

Creating a project#

If your organization doesn't have the project yet, create one from the Desktop App or the web app. You can start from a template - Blank, Media & post, Software (git repository), Revit worksharing, or Geospatial - which pre-sets sensible defaults (encryption tier, commit mode, default-branch protection). Media & post, Revit worksharing, and Geospatial also seed a starter folder layout plus an ignore file so everyone begins from the same shape; Software (git repository) seeds just the ignore file, and Blank starts empty. A template that seeds an ignore file can't be used on an end-to-end encrypted project - the hub holds no key, so the create is refused; start Blank there, or create the project on a plaintext or managed tier and keep the seed.

Two creation choices are fixed and worth a moment's thought. The initial branch is the name of the project's default branch: most projects keep main; choose another (for example develop) only if your tooling expects it. It can't be changed later, it's the branch a fresh clone checks out, and the web app opens the project on it - so git clone of a project whose default is develop lands on develop, and its Files, Commits and Runs views start there too. The encryption tier - managed (the default), end-to-end, or plaintext on a public project - is also fixed at creation; upgrading later doesn't retroactively encrypt an existing project. See Security Architecture.

To inspect a project's effective settings - every option's value and where it came from - run swarmfile project show; change them with swarmfile project set <key=value> (see the CLI reference).

Mounting a project#

Once signed in, the Desktop App shows the projects you have access to. Pick one and it appears as a drive on your machine - a drive letter on Windows, a mount point on macOS and Linux. The exact location is in the Desktop App's header: click the Status pill to open the panel showing the mount point and sync state. It's assigned at mount time and can vary between machines (for example, if a default drive letter is already taken, Swarmfile picks the next free one).

From here, the mount behaves like any other local filesystem. Open it in Finder, Explorer, or your file manager, or point a native app directly at a file inside it.

First open#

The first time you open a file, only the bytes your application actually reads are streamed down. Scrubbing 30 seconds into a 200GB video timeline streams roughly 30 seconds of footage, not the whole file. Browsing folders, previewing thumbnails, and listing directories don't trigger downloads at all - that metadata is served directly.

Presenting the Desktop App#

Cmd/Ctrl+Shift+P toggles presentation mode, the on-camera switch for demos and screen recordings. Text scales to the largest size so a 1080p capture stays readable after compression, and names, emails and organization names are replaced with stable pseudonyms ("Person AB") so a customer's details can't slip into a video. The switch is local to your machine - it never changes what teammates see.

Prefer larger text all the time, no recording involved? The Desktop App's Settings → Text size offers Compact, Default and Large steps for that computer (Cmd/Ctrl + and − step it, Cmd/Ctrl 0 returns to Default); presentation mode always uses the largest step.

For multi-machine demos, presentation mode can also show a small always-on-top clock overlay, with the time synced from the network so machines shown side by side agree.

Where to go next#

Working with Files covers browsing, saving, presence, and locking in more depth.
New to Swarmfile's own version control? Version Control covers changesets, branches and rollback, and Branches & Merging covers working an option in isolation and landing it.
Working in git? Clone a Project with Git covers git clone swarmfile:// and git push against a project's git view, and Git and Swarmfile lays out the three ways the two fit together. Starting from a repository that already exists elsewhere? swarmfile git import <url> creates the project from it in one command - see the import reference.
If you're moving data in from an existing NAS or file server, see Migrating Existing Data.
Rolling this out to a whole team rather than installing by hand? See Deploying to Your Team.