Multiple Mounts

A Swarmfile engine can host more than one mount at a time, so you can work in two projects - or two branches of one project - side by side on the same machine, each as its own drive. This is the quick, human-facing version of the setup described for automated fleets in Coding Agents.

When to open a second mount#

• Two projects at once - a live project and a prep project, or two clients you switch between all day.
• Two branches of one project - compare a look-dev branch against main without switching the whole drive back and forth.
• An agent or script that needs its own workspace - a second mount keeps its changelists and locks separate from yours.

Each mount is a full, symmetric mount: its own branch, its own open changelists, its own lock state. Nothing you do in one changes the branch the other is on.

Opening one#

In the Desktop App, hover a project in the left rail and click its + to open that project as another drive, or use + Open another drive… under the projects list, the + half of the mount switcher (the drive name at the top of the window), or + Open another drive… inside the switcher. Each opens the Open a drive dialog, where you pick:

• the project (preselected when you came from a project's +) and optionally a branch;
• an optional name so you can tell drives apart ("agent-2", "client-b") - the same thing the CLI calls a label (--label).

Swarmfile chooses where the drive appears - the next free drive letter on Windows, and a new folder beside your main drive on macOS and Linux, named after the drive (or its branch) - and the dialog shows the exact letter or folder before you open it. To pick a specific drive letter or an empty folder of your own, open Advanced. If a drive can't open, the dialog says why straight away - for a taken drive letter it offers the next free one - and the failed drive never becomes the current one. A drive that is slow to attach closes the dialog and shows Connecting… in the list (it can't be switched to until it's ready); Swarmfile switches to it once it's live, unless you've moved to another drive in the meantime, and a notice says how it went.

From the CLI, the same thing:

swarmfile mounts open Y: --label client-b                    # Windows: a drive letter
swarmfile mounts open auto --label client-b                  # Windows: next free letter
swarmfile mounts open ~/swarmfile/client-b --label client-b  # macOS/Linux: a folder
swarmfile mounts open Y: --label dev --branch look-dev-warm  # pin this mount to a branch
swarmfile mounts open Y: --label side --project proj_…       # a different project (same org)
swarmfile mounts open ~/agent-2 --exclusive                  # exclusive-write mode (agent fleets)

On Windows the folder or drive letter must be free - an existing non-empty folder is refused rather than mounted over, while an existing empty folder is accepted (the app's folder picker only returns folders that already exist, so this is the normal second-mount shape). On macOS and Linux the mount point is a normal folder, and the same path can't be used by two mounts at once. See Filesystem Compatibility for the per-platform details.

Keeping two agents off the same file#

Locks protect a file against other people and machines, but two mounts of one engine share one machine identity - so by default nothing stops two agent mounts from editing the same file at the same time, with the last save winning. If that matters (several agents working the same tree), open each agent's mount with --exclusive:

swarmfile mounts open ~/agent-1 --exclusive --label agent-1
swarmfile mounts open ~/agent-2 --exclusive --label agent-2

Exclusive-write mode is opt-in per mount. While one exclusive mount has a file open for writing, another exclusive mount on the same project+branch has its write-open refused - with EAGAIN on macOS and Linux, and on Windows with the sharing violation apps report as "file in use" - and a rename, delete, or atomic-save replace of that file is refused too, so the holder's file can't be moved, replaced, or removed out from under it. The refusal is recorded (with the holding mount) in the tray's blocked-writes view and in swarmfile status. Closing the file - or finishing its save - releases the claim. A mount opened without --exclusive neither takes nor honors claims, so your human drive and non-exclusive mounts behave exactly as before; the protection is between the mounts that opted in.

In the desktop app the same option is the Prevent another drive from editing a file this one has open checkbox under Advanced in the Open a drive dialog, and an exclusive drive carries a lock badge in the drive list. Like the flag, it is fixed when the drive opens - close and reopen the drive to change it.

Working with several mounts#

• swarmfile mounts list - every mount, its label, branch, project, and which one is current.
• swarmfile mounts current <id> - choose which mount commands without an explicit target should act on.
• swarmfile --mount <id> status - run any command against one specific mount, without changing the current one. Write the flag before the subcommand.
• swarmfile mounts branch <id> <branch> - move one mount to another branch without touching the others.
• swarmfile mounts close <id> - shut one down. It refuses while a changelist is open (--force abandons it), and it always refuses the boot mount.

The Desktop App does the same: each project in the left rail lists its open drives underneath, each row showing the drive's path, branch and status with a control to make it current and a × to close it.

Limits and practical notes#

• macOS: each FUSE-T mount takes one helper port from an 18-port range, so a Mac supports at most 18 mounts at once. If an open fails saying the port range is exhausted, close a mount or clear leaked helper processes.
• One engine, one cache directory. Don't point two engines at the same cache directory or mount point. Running a separate engine per mount is a valid isolation choice, but it must have its own SWARMFILE_CACHE_DIR.
• Shared scratch cache. All mounts of the same project on a machine can share one scratch directory for tool caches, so a second mount doesn't re-download dependencies - see Coding Agents.
• Switching the whole engine is different from picking a current mount: swarmfile workspace switch moves the engine's active org/project - usually in place, without a restart; it falls back to a brief unmount-and-restart only when the hot path cannot complete - while mounts stay put. See Switching the active organization or project.

Where to go next#

• CLI: swarmfile → mounts - every mounts subcommand and flag.
• Working Offline (Pack & Go) - reserving a scope on one mount for offline work.
• Coding Agents - the headless, one-mount-per-agent version of this setup.