Sharing & Collaboration

Swarmfile has two collaboration surfaces: tools for your own org members working inside a project (comments, watch, presence), and tools for getting a specific file or folder in front of someone who isn't a member at all (share links, external collaborators). This page covers both, plus how they interact.

Comments and mentions#

Every file has its own comment thread. Post from the CLI with swarmfile comment <path> -m "message", or list a file's thread with swarmfile comments <path>. The web dashboard has a full thread panel with @-mention autocomplete for tagging teammates.

Threads live-update over SSE - anyone with the file open in the dashboard sees new comments and mentions arrive without refreshing.

A comment can be a reply, not just a new top-level note - click Reply under any comment to keep a back-and-forth in one thread instead of scattering it across separate top-level posts. Replies are one level deep (no reply-to-a-reply); resolving is a thread-level action on the original comment, not on each reply individually.

On an image preview in the web dashboard, click Add pinned comment, then click a spot on the image to leave a comment anchored to that exact location - useful for pointing at a specific area of a render or drawing instead of describing it in words. Pinned comments show as small markers on the image and, everywhere else the thread appears (including the tray), as a 📍 badge next to the comment. Pinning is web-only in this version; PDFs and other file types don't support it yet.

Watch#

Watch is a targeted, opt-in subscription to a specific file or folder, distinct from the general "someone else changed a file" bell notification you get for activity across a project. You choose exactly what you want notified about.

Watching a folder is automatically recursive - you don't pick recursive vs. non-recursive, the server derives it from whether you watched a file or a folder.

• swarmfile watch <path> - start watching a file or folder
• swarmfile unwatch <path> - stop
• swarmfile watches - list everything you're currently watching

Watch is also available outside the CLI: the tray's file list has a per-row watch toggle, and the web dashboard exposes watch/unwatch from the right-click context menu on a file or folder.

A watched-file change reaches you through the notification bell and a tray toast; how notifications are delivered, and which kinds can also be emailed, is covered in Notifications & Inbox.

Presence#

Presence shows who's actively editing what, in real time. Run swarmfile presence (or the shorter alias swarmfile who) to see it from the command line, or check the dashboard for the same view. Presence is tied to the entry lock lifecycle, not a free-running heartbeat - see Working with Files for how locking and presence relate.

Share links#

A share link publishes a single file or folder to anyone with the URL, without giving them a Swarmfile account or a seat.

When you create a link you can add:

• A password, checked against a PBKDF2 hash - the file's contents are never exposed by the password mechanism alone, see below
• An expiry date
• A cap on total access count

The access-count cap is enforced by the hub for managed-key shares. On an end-to-end encrypted project it is best-effort only: the recipient's browser fetches raw ciphertext blocks and decrypts them locally with the key carried in the link, so retrieval isn't metered server-side and the cap won't bind - use an expiry, or revoke the link, to bound an E2E share. (The share dialog hides the access-count field for E2E projects for exactly this reason; expiry, revocation, email verification, and the per-recipient block list all still apply.)

Every share link requires email verification, regardless of whether you've also set a password. Before a recipient can see any content - download, preview, or the comment thread - they have to enter their email and click a one-time magic link sent to it. This isn't optional and it isn't skippable by knowing the password: the password (if set) and the email verification are both required, independently. Once verified, a recipient gets a 30-day session, so a returning collaborator isn't re-verified on every visit.

This gives the share owner a real access log: every verified recipient, by email address, with when they accessed the link. You can block any individual recipient from that log at any time, and the block takes effect on their very next request - an already-open browser tab doesn't get to keep working.

Shares support inline preview for images, PDFs, and text files, plus an optional public comment thread scoped to the shared item.

External collaborators#

External collaborators are named guest reviewers - an M&E client, an AEC consultant - invited to a specific folder with read or comment permission, without consuming a paid seat. See Permissions for how folder-level access grants work generally; external collaborators are layered on top of that same system, scoped to a folder rather than a whole project.

What a guest gets:

• A kernel-level read-only mount of the folder they were invited to. This is enforced below the filesystem layer, not a UI restriction - a read-permission guest cannot write to the mount even by bypassing the dashboard entirely.
• An offline-first comment and upload queue in the tray, for guests with comment permission.
• Instant revocation and a full audit trail on the org side.
• If the same person is invited to multiple orgs as a guest, they get a picker in the tray to switch between them.

External collaborators are plan-gated: Starter includes 1 per seat, Pro includes 5 per seat. Both plans allow billed overage up to 3x the included allowance before new invitations are hard-blocked - see Billing & Plans for how overage is metered and charged.