Working with Files

Your mounted drive is a normal filesystem to any application - Resolve, Premiere, Revit, QGIS, Explorer, Finder, whatever you point at it. This page covers what's different about working with files on Swarmfile: the web dashboard's view into the same data, and the mechanics of saving, presence, and locking that run underneath.

Browsing#

The web dashboard's Files view gives you a folder tree alongside a sortable table (name, size, modified date, and who last touched a file). This is a separate view onto the same underlying storage as your mounted drive - useful for checking file history or activity without opening a native app. On the mount itself, browsing is just normal folder navigation, and it costs no disk space: listing a directory doesn't download anything in it.

When someone else saves a file, it appears in your file manager within a couple of seconds. Your operating system caches directory listings for a short window, so a folder you already have open can be a moment behind; reopening it or pressing refresh always shows the current state.

The web dashboard additionally renders thumbnails and inline previews - including video posters, scrubbable proxies, and point-cloud previews - so you can eyeball a folder without opening a native app. See File Previews.

Opening and saving#

Opening a file streams the bytes your application reads - and only those bytes.

The recording above is the whole idea in three commands: listing a file costs nothing, and reading part of one costs that part. Scale it up and it is why a 200 GB sequence opens on a laptop with 40 GB free. Saving is asynchronous: a write returns as soon as it's queued, not once it's fully uploaded. A durable local upload queue handles the actual transfer in the background, with automatic retry on failure.

That recording is the same point from the writing side: the save returns at local-disk speed with hundreds of blocks still queued behind it. Because the queue is durable, it survives a restart or a dropped network connection - pending uploads resume automatically rather than being lost. You are never blocked waiting for a save to finish uploading before you can keep working.

While a large file is still uploading#

The queue draining in the background is invisible on a fast link. On a slow one it isn't: a very large file on a modest uplink can take hours or days to finish, and until it does, the new version isn't something anyone else can open.

While that transfer is running, the file's page in the web dashboard shows an Uploading badge, along with which machine is sending it. The row itself still describes the version everyone can currently read - same size, same date, and Download still works - because a version in progress never replaces the one people are already using. Nothing becomes unavailable because a colleague started saving.

If you need part of that new version before it has all arrived, you can ask for it, and the uploading machine will send that part first:

swarmfile fetch ./Projects/reel-04.r3d --tail 209715200

That is the last 200 MB of a file still in transit. The request travels to whichever machine is uploading, that machine moves the blocks covering your range to the front of its queue, and you get them in roughly the time it takes to send that range - rather than waiting out the whole file. Uploads are sent in order from the start of the file, so without asking, the end is the last thing to arrive.

It is worth knowing what this does and doesn't do. It changes which bytes arrive first, not how fast the link is: the last 20% of a 5 TB file is still 1 TB, and 1 TB still takes as long as 1 TB takes. What it removes is the wait for the other 4 TB you didn't need.

The bytes land in your local cache, pinned so they aren't evicted before you open the file. Release them with swarmfile hydrate release when you're done - see the CLI reference. Reading the file normally through the mount is unaffected and gives you the committed version - unless the mount has been opted into streaming, below.

Watching a file as it uploads#

A single range is the right shape for "give me the last 200 MB". It is the wrong shape for watching, because a viewer moves: it plays forward, and it seeks. --follow tracks that.

# Start following from the beginning
swarmfile fetch ./Projects/reel-04.r3d --follow --version pending

# …and tell it where the viewer has got to
swarmfile fetch-seek 5000000
swarmfile fetch-status

Instead of completing at a fixed range, a follow job keeps a buffer ahead of wherever the reader is and re-targets when it moves. The uploading machine is told about the new position immediately, and - this is the part that matters - the new request replaces the old one rather than queueing behind it, so it stops working on the stretch you scrubbed away from.

How far ahead it buffers is measured, not configured: the read position's own rate of advance is the consumption rate, so a 6 Mbit/s proxy gets a small window and a 200 Mbit/s master gets a proportionally larger one, both covering the same number of seconds. SWARMFILE_STREAM_BUFFER_SECS sets that number (default 30). A seek is not mistaken for playback.

Opening an in-progress upload directly (opt-in)#

Everything above puts bytes in the cache. There is also a mode where a file that has never finished uploading is simply openable - it appears at its full eventual size and reads work, waiting briefly where the bytes have not landed yet.

This is off by default. Turn it on per machine with stream_in_flight in config.json, or SWARMFILE_STREAM_IN_FLIGHT=1.

Off by default because a read into a range that hasn't arrived has to wait, and a filesystem operation that waits too long doesn't stall one read - it takes the whole drive with it. The wait here is strictly bounded (15 seconds, see SWARMFILE_STREAM_READ_WAIT_SECS) and a read that outruns the upload returns "try again" rather than an I/O error, precisely so an application doesn't conclude the file is damaged. But that bound has not yet been measured against a real NLE on both platforms, and until it has, this stays something you switch on deliberately.

Two things to know about the scope:

• It applies only to files with no committed version yet - a new master landing for the first time. A file you are already reading never changes size or content underneath you because somebody started a new save. That is the same rule the rest of the product follows, and it matters more than the feature does.
• If the uploading machine is on your LAN, it will serve those blocks to you directly, from its own disk, before they have reached the cloud at all. Across the internet it won't: that would put every block on the same congested uplink twice.

The honest limit. None of this makes the link faster. It makes the right bytes arrive first. A 4 TB file on a 100 Mbit/s uplink delivers about 12 MB/s however well it is ordered - comfortable for a proxy, not for a full-resolution master. The reliable version of this workflow is "watch the proxy while the master uploads", and on a LAN, where the uploader's own disk is the limit rather than its uplink, considerably more than that.

Deleting#

Delete from the drive exactly as you would any other file - your file manager, or rm. Deleted files go to Trash rather than disappearing, and are restorable for as long as your organization's retention window allows: see Trash, History & Rollback.

Two behaviors worth knowing. A folder cannot be removed while it still contains files - empty it first, because deleting a folder would take everything inside it with it, and that is a bigger action than "remove this folder". And if a file is open or locked by someone else, the delete is refused rather than queued: your file manager reports it, and the tray's Presence view shows who has it.

Presence#

The dashboard shows a real-time "who's editing what" indicator. This is tied to the entry lock lifecycle, not a free-running heartbeat - it reflects files that are actually open and locked, not just which teammates are online. If presence shows someone on a file, they hold (or recently held) a lock on it.

Entry locks#

Locking a file blocks other users from writing to it until you release the lock or it expires. Locks have a 60-second TTL and are renewed with a heartbeat while the file stays open in your application - you don't need to manually extend them. If your app crashes or your machine loses connectivity, the lock expires on its own within 60 seconds rather than staying stuck.

Byte-range locking#

Entry locks cover a whole file. For native worksharing apps that need to lock just part of a file - the way a Revit-class BIM tool locks the elements one person is editing without blocking everyone else out of the same model - Swarmfile exposes a separate, lower-level byte-range locking API. This is what a CAD/BIM plugin integration would call directly. The swarmfile-brlock CLI is the reference client for that API.

File and folder watch#

Watch is distinct from the general "someone else changed a file" bell notification you see for activity across a project. Watch lets you subscribe to a specific file or an entire folder and get notified when it changes - useful for scripting a rebuild step or keeping an external tool in sync with a subtree of a project without polling it.

If the drive stops responding#

Occasionally the drive can stop answering: files won't open, a Finder or Explorer window sits there, and the application waiting on it may not even force-quit cleanly.

That behavior is deliberate, and it's the safer of two bad options. The drive is mounted to wait rather than to fail, because a filesystem that returns an error partway through a write can leave an application believing a save succeeded when it didn't - which on a multi-hundred-gigabyte project file means silent corruption. The cost of that choice is that a drive which stops answering waits indefinitely instead of erroring.

Swarmfile watches for this and reconnects the drive on its own where it can. While that's happening the tray reports the drive as unavailable rather than continuing to show a healthy mount - if the tray says the drive is there, it's there.

When it doesn't clear by itself, open the tray, go to Settings → Diagnostics, and use Repair drive. It reconnects the drive in a few seconds and touches nothing else - your queued uploads are held in a durable local queue, so nothing waiting to upload is lost, and you don't need to quit and reopen Swarmfile.

If repairing doesn't help, Reinstall… on the same panel replaces the whole install, and a restart of the computer clears anything left. For working out whether the underlying problem is your network, your account, or the service, run swarmfile doctor - its output is what support will ask for first.