Performance & Disk Usage

Swarmfile is fast by default for the two things people notice - opening files they have touched before, and saving without waiting. When it isn't, it's almost always one of two resources: local disk (the cache) or the network path a file took (LAN peer, seed node, or cloud). This page covers both, plus how to keep the cache from growing into a laptop's free space.

The local cache#

Every file you read is copied into a local block cache and kept there until space is needed. The cache is not a copy of the project - it holds what you have actually touched, newest first, and trims itself as it fills.

• Default size: 10 GiB, per machine and per user.
• Change it in the Desktop App's settings, or from a terminal: swarmfile cache set 50 (GiB), or swarmfile cache status.
• The mount always reports at least 1 GiB free to applications, so an app's "disk full" is about your actual local disk, not the cache being full-but-evictable.
• A seed/NAS node is the exception: it pins whole projects by design, so size its disk for the projects it serves (the sample seed config suggests 100 GiB as a starting point).

Files you want resident on purpose - a render source tree, a site archive - should be pinned rather than left to the LRU:

swarmfile hydrate start ./shots/seq010 --yes   # download and pin (no prompt)
swarmfile hydrate status                       # progress of the current job
swarmfile hydrate release ./shots/seq010       # unpin when done

Pinned content can exceed the cache cap; it is never evicted, so don't pin more than the disk can hold.

Making reads fast#

Reads come from, in order of preference: the local cache, a LAN peer that has the file, a seed node, then cloud storage (via a presigned URL direct to the org's bucket - not through the hub). Two things follow:

• The first person to open a file pays for it; everyone else in the office gets it over the LAN. If transfers look like they are coming from the cloud when peers exist, check swarmfile status for the peer count, then run swarmfile-doctor: the mdns listen and host firewall checks name the usual causes.
• Pre-hydrate the hot set. For a render farm or a shoot day, hydrate start before the job starts beats streaming during it. swarmfile uploads --wait is the matching pre-flight when you need an upload to have landed before reading it elsewhere.

For a single very large file, ask for the part you need instead of the whole thing:

swarmfile fetch ./plate.exr --tail 209715200      # last 200 MB
swarmfile fetch ./plate.exr --follow              # track a moving reader (playback)

Metadata-heavy workloads (thousands of small files, or an app that stats before it opens) benefit from a larger attribute cache: swarmfile attr-cache set 10 (seconds; macOS/Linux). CAD tools that open external references can leave xref prefetch on (the default) or turn it off for a pathological reference graph - see Environment Variable Index.

Where the bytes came from#

To see that preference order in action - on a live project, per file - open the Desktop App's Data sources panel (left rail → Data sources). It shows, for each file and in total, how much of what you read came from this computer, from a colleague's computer (a LAN or WAN peer), and from the cloud, with first-read times. Reset counters starts a fresh measurement window; the process-wide bandwidth numbers restart with it. A one-line version sits in the header's Status popover.

The same numbers are on the command line - the form to use when they need to end up in a spreadsheet or a bug report:

swarmfile stats              # per-file table
swarmfile stats --json       # full report: version, machine, mount path/branch, sizes, timings, bytes by source
swarmfile stats --csv        # one row per file for a spreadsheet
swarmfile stats --reset      # zero the counters after printing

For a genuinely cold start - a benchmark, a demo, or "is the LAN actually being used?" - swarmfile demo reset empties this machine's cache for one project (the same whole-project sweep as Free up space, including offline pins; never unsynced saves) and zeroes those counters, so the next run measures from zero. Run it on every machine involved; see swarmfile demo reset.

Bandwidth and schedules#

Throttling is off by default. If your office link is shared and Swarmfile's background traffic is crowding out people's calls, turn it on with a real link size first:

swarmfile throttle enable \
  --download-mbps 500 --upload-mbps 100 \
  --office-hours-start 08:00 --office-hours-end 18:00 \
  --office-hours-wan-pct 20 --off-hours-wan-pct 80

That allows 20% of the link to WAN transfers during office hours and 80% outside them; LAN traffic and app-requested reads are not held back by the schedule. Status and changes: swarmfile throttle status / swarmfile throttle disable.

Two behaviors worth knowing:

• Turning throttling on with no bandwidth set applies a guessed symmetric cap (about 100 Mbps), so always set the link size.
• Interactive traffic (opens, small reads, saves' control calls) is marked for priority over bulk transfer (DSCP, when your network honors it). You rarely need to touch the DSCP values; they exist for networks that prioritize by tag - see the Environment Variable Index.

Uploads are designed not to block#

A save returns as soon as the bytes are safely queued locally; the upload continues in the background, survives restarts, and resumes by itself. A 500 GB file on a 100 Mbps uplink will take days to reach the cloud, and that is expected - not a stuck sync. swarmfile uploads shows what is still in flight (across all machines, not just yours), and --wait blocks until nothing is. Other people can fetch the part they need before the upload completes - see While a large file is still uploading.

If a save isn't landing, it is on the stuck list, not the upload list: swarmfile sync stuck says why and for how long, and the Desktop App's header says N changes not syncing or N changes failed.

A burst of many small files is a different shape from one large one. Each save needs a handful of control-plane calls, and Swarmfile paces them to the hub's request allowance for your plan, so a mass overwrite of hundreds of files converges over minutes while the header counts up to Synced. That is deliberate pacing, not a stall - the work is durable throughout, and a restart resumes it.

Freeing up local disk#

In rough order of how much they return:

1. Let the cache do it. Lowering the cap (swarmfile cache set 5) applies immediately and evicts unpinned content down to the new size, no restart. (swarmfile cache reclaim looks similar but isn't a general eviction command: it removes a legacy pre-project-scoping cache directory that is only kept as a read-only fallback, and it has a --dry-run to preview.)
2. Release deliberate pins you no longer need: swarmfile hydrate release <path> followed by swarmfile hydrate free-space <path> (or Free up space in the tray). Free up space never touches unsynced changes.
3. Remove content that should never have synced. If a project synced node_modules/ or render caches before an ignore rule existed, swarmfile check-ignore <path> confirms the rule, and swarmfile ignore-clean removes the already-synced content (a soft delete; recoverable from Trash).
4. Empty Trash and old branches. swarmfile trash purge and swarmfile branch prune shrink the hub's storage; freeing server-side space is not about your laptop, but it matters for the org's allowance.
5. Build caches are separate. Tool caches live in the project scratch directory, not the block cache: swarmfile scratch gc reclaims stale ones, and swarmfile mounts scratch-dir <id> prints where they are. See Coding Agents.

If the Desktop App's disk usage is still surprising, check the size of the cache directory itself (~/.cache/swarmfile, %LOCALAPPDATA%\swarmfile) and compare it to the configured cap - pinned/hydrated content legitimately exceeds the cap, and swarmfile hydrate status lists what is pinned.

Diagnosing "everything is slow"#

1. swarmfile status - peers in the office, in-flight uploads, commits waiting, stuck saves.
2. swarmfile doctor - DNS, hub reachability, mDNS, firewall, and the LAN-consent checks.
3. Check whether the slowness is first open (network) or every open (local disk or an app doing its own scanning). First opens are expected to be slow for a file nobody nearby has; repeat opens should be cache-speed.
4. Very large projects: a project with millions of files and versions can make full-project browsing and history feel heavier - history retention and project splitting are in Operations.

Where to go next#

• Working with Files - sync status, freeing up space, and watching an upload.
• Working Offline (Pack & Go) - reservations for field work.
• Deployment Topologies - seed nodes and LAN-first office design.
• Environment Variable Index - every cache, streaming, and QoS tunable.