Shares belong to one device and are read-only for the others. The swarm folder belongs to the whole swarm: any device can add files and folders, rename them and delete them, and every other device sees the change.

Using it

In the app, open Swarm folder (on phones, Swarm in the navigation bar). The header shows how many items it holds, how many devices it last synced with and when. From there:

• Add file… picks a file with the system picker and adds it.
• New folder creates a folder at the current place in the breadcrumbs.
• Each row can be downloaded, renamed or deleted; tapping a file opens the same viewer as browsing a device.
• The Added by column (on wide windows) names the device that added each file.

On Linux it is also <mount>/Swarm in the mount, where any program can write to it (see below).

How changes travel

The swarm folder’s listing is a manifest: every path with its kind, content hash, size, modification time and author. Each device keeps the whole manifest on disk, next to its block store, and merges it with every reachable device every 10 seconds.

The manifest is a state-based CRDT: two devices that have seen the same edits hold the same manifest, whatever order the edits arrived in. No device is in charge and none has to be online for the others to keep working.

File contents are not in the manifest. A file’s bytes stay on the device that added it and travel when someone opens it: from the local cache first, then from the device that added it, then from any device that has it cached.

Backup devices

A file added from a phone is only readable while that phone is reachable, unless another device has a copy. A backup device keeps a copy of every file in the swarm folder: give the job to a computer that stays on, such as a desktop or a home server, and the folder stays readable when the phone is off.

• In the app (Linux desktop): Settings → Swarm backup → Back up the swarm folder here. The card shows how many files are backed up.
• On the command line: --swarm-backup, or in the configuration:

[storage]
swarm_backup = true

Every 10 seconds the backup device copies each new file, block by block, verifying every block against its hash. It asks the device that added the file first, then any other device that has a copy, so two backup devices also back each other up. It remembers what it copied (<storage_path>.swarm.json.backup), so a restart doesn’t check everything again. Other devices need no setting: when the author is offline they try every known device, and the backup answers.

The copies stay when a file is deleted or replaced: the space they use isn’t reclaimed yet. A file that no reachable device has, because its author has been offline since adding it, is copied once the author is back.

Conflicts

Every entry carries a version (a Lamport clock and the device that made it) and remembers the last 8 versions it replaced. When two versions of the same path meet:

• If one has the other in its history, it is the newer edit and wins.
• If neither does, the edits were made at the same time. Both are kept: the higher version keeps the name, and the other is renamed to name (conflict from <device>).ext. Every device computes the same name, so the swarm agrees without talking about it.
• A delete never beats a concurrent edit: the edited file stays.
• Deletes are recorded as tombstones, so they replicate like any other edit.

What a device receives from its peers is validated before it is merged: path length (1024) and depth (32), entry count (100,000) and author names are bounded, and unsafe paths are refused.

Writing from the mount

<mount>/Swarm behaves like a normal folder for editors, file managers and the shell:

• Writes go to a staging file first; reads see them straight away. When the file is closed it is chunked and added to the swarm as one edit, so other devices never see half a write.
• Creating, truncating, appending, mkdir, rm, rmdir (refused while the folder is not empty) and mv anywhere inside the swarm folder work, including an editor’s save-to-temporary-then-rename over an existing file.
• A renamed folder keeps its contents visible at the new path at once.
• Moving files between the swarm folder and a device share fails with EXDEV (a cross-device move); writing to a device share fails with EROFS.

Files in Swarm show as 0644, folders as 0755.