Uninstall & Clean Reinstall

Removing Swarmfile from a machine is straightforward, with one important distinction: repairing an install and removing one are different operations, and repair is almost always what you want. If the app is misbehaving - a broken mount, a missing CLI tool, a half-applied update - use Diagnostics → Reinstall… or swarmfile-doctor --repair --yes instead. A repair reinstalls the full package and keeps your cache, queued uploads, config, and sign-in; removing the app and its data does not. A repair stops the engine briefly while the installer runs (on Windows the drive is detached cleanly first) and it reconnects when the install finishes; queued work is unaffected.

Everything below is for a deliberate removal - decommissioning a laptop, handing it to someone else, or a truly clean slate.

Before you remove anything#

Three things live only on this machine and are lost when you delete its data:

1. Queued uploads. Saves that haven't reached the hub yet live in the local database. Check swarmfile status (the pending uploads / commits pending counters) and swarmfile uploads --wait; wait for zero, or accept losing those changes.
2. Stuck saves. swarmfile sync stuck lists saves the hub keeps refusing. Export or resolve them before wiping the cache - they will not come back.
3. Reservations and locks. swarmfile offline return releases any Pack & Go reservations this machine holds; checkout locks you took expire on their own lease, but releasing them now is neighborly. If this machine runs a seed node, disable seed mode first (swarmfile seed disable) so the org's discovery list doesn't keep advertising it.

Anything staged in a changelist that has been parked is kept on the hub and can be resumed from another machine; unsent changelist work is local and goes with the cache.

One more piece of wiring is separate from the app install: if this machine used a project as a git-LFS server, run swarmfile-lfs uninstall to remove the custom-transfer adapter from your git configuration. Uninstalling the app does not do that for you.

Windows#

1. Quit the Desktop App from the tray (including any "quit engine" option so the mount dismounts). The uninstaller stops the engine and tray itself (with a force-kill backstop), but quitting first avoids holding the mount open.
2. Uninstall from Settings → Apps → Swarmfile → Uninstall. For scripted removal, find the product code and call msiexec (the CI harness does the same):

   $key = Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall',
                        'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall' |
     Where-Object { $_.GetValue('DisplayName') -match 'Swarmfile' } | Select-Object -First 1
   msiexec /x $key.PSChildName /qn /norestart
   

   If the install came from the bundled Setup.exe, its uninstaller lives in ProgramData\Package Cache; Settings → Apps invokes it with /uninstall for you.
3. The uninstaller removes the program files (C:\Program Files\Swarmfile), the PATH entry, the swarmfile:// protocol registration, the inbound UDP firewall rules, the Explorer overlay handlers, the Start Menu shortcut, the per-machine Run entries, and the Swarmfile Updater scheduled task. WinFsp, the VC++ Redistributable, and WebView2 are chain prerequisites and deliberately stay installed.
4. Per-user data is deliberately left behind (uninstalling for one user shouldn't wipe another's cache):

   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\swarmfile"
   

   This removes the cache, queued uploads, config, and sign-in for that user only. One leftover is harmless: HKCU\Software\Swarmfile\MountPoint (the remembered drive letter), which the MSI doesn't own.

To reinstall, run the bundled Setup.exe again - or a repair if you only wanted the app fixed.

macOS#

The .pkg install is machine-wide: the app in /Applications, LaunchAgents in /Library/LaunchAgents, and CLI symlinks in /usr/local/bin. Removing it takes a few commands; run the launchctl lines as the logged-in user and the rm lines with sudo.

1. Quit the Desktop App, then stop its background services:

   launchctl bootout gui/$UID/dev.swarmfile.tray 2>/dev/null
   launchctl bootout gui/$UID/dev.swarmfile.engine 2>/dev/null
   

   (A staging install uses a namespaced label - check launchctl list | grep swarmfile for the exact names.)
2. Remove the app, the agents, the CLI links, and the bundled FUSE-T pieces:

   sudo rm -rf /Applications/Swarmfile.app
   sudo rm -f /Library/LaunchAgents/dev.swarmfile.engine.plist \
              /Library/LaunchAgents/dev.swarmfile.tray.plist
   sudo rm -f /usr/local/bin/swarmfile /usr/local/bin/swarmfile-* /usr/local/bin/go-nfsv4
   sudo rm -f /usr/local/lib/libfuse3.4.dylib /usr/local/lib/libfuse3.dylib \
              /usr/local/lib/libfuse-t-1.2.7.dylib /usr/local/lib/libfuse-t.dylib
   sudo rm -rf "/Library/Application Support/fuse-t"
   sudo pkgutil --forget dev.swarmfile
   

3. Remove the per-user data (cache, queue, config, token):

   rm -rf ~/Library/Caches/swarmfile ~/.cache/swarmfile ~/.config/swarmfile
   

   The engine's cache and config are the ~/.cache/swarmfile / ~/.config/swarmfile pair; ~/Library/Caches/swarmfile covers .dmg/legacy layouts. Repeat per user profile.

If Finder or an app still shows the drive, it is a stale mount from a killed helper - log out and back in, or reboot, before wiping. swarmfile-doctor --repair --yes is the supported way to fix an install you intend to keep.

Linux#

1. Quit the Desktop App and the engine for each logged-in user first - the package's pre-remove script disables the systemd units but does not stop services already running in your session, so a removed engine can keep serving its mount until you log out or kill it.
2. Remove the package:

   sudo apt remove swarmfile      # remove the app and units
   sudo apt purge swarmfile       # also remove the packaged /etc/swarmfile
   

   Removal disables the per-user swarmfile-engine and swarmfile-tray systemd units; nothing else (firewall, mounts) is touched. If a mount is still present after removal, unmount it (fusermount -u <mount point>) or log out.
3. Remove the per-user data for each user who signed in:

   rm -rf ~/.cache/swarmfile ~/.config/swarmfile
   

   That covers the cache, queue, config, and token. If you ran a seed or a headless engine with its own SWARMFILE_CACHE_DIR, remove that directory too.

What lives where#

The cache directory is also where log files live, so if you're removing the machine as part of a support case, copy that directory aside first.

Clean reinstall#

To start completely fresh on the same machine:

1. Follow the uninstall steps above, including deleting the per-user data.
2. Install the current package from swarmfile.com/download - or, on macOS, make sure it's the .pkg: the .dmg doesn't set up the engine service or the CLI on PATH.
3. Sign in again and re-open the project. The mount comes back where the Drive Letter / mount-point settings say; nothing on the hub is affected by the reinstall.

Where to go next#

• Release Channels & Updates - how updates work and what a repair does.
• Supported Platforms & System Requirements - installer names and per-platform layout.
• Deploying to Your Team - removing or re-provisioning machines at fleet scale.