Contract and limits
What a mount guarantees on one machine and across machines, what is not supported, durability, the service stage, quotas, known issues and platforms.
This page says what to expect from a mountable.io filesystem before you rely on it. Behaviour marked verified is shown by our automated tests, which mount filesystems on Linux. Behaviour marked not verified is how the service is built to behave, not yet covered by a test, and not a promise. What our qualification runner checked on a Mac is listed under platforms.
On one mount
One mount behaves like a local directory for these operations:
| Operation | Status |
|---|---|
| create, write, read, append | verified |
| truncate | verified |
mkdir, list a directory, rmdir, recursive delete | verified |
| rename files and directories | verified |
| hard links, within one filesystem | verified |
| symbolic links | verified |
chmod | verified |
| unlink a file that is still open: it stays readable | verified a few seconds after the unlink; not verified for longer, and reads a day or more later can fail |
| a 24 MiB file reads back byte for byte, also from a later mount | verified |
| a read-only mount reads, and refuses writes | verified |
extended attributes, timestamps (utimens), fsync, fallocate, copy_file_range, statfs, flock and byte-range locks, mmap | not verified |
Across mounts
Several machines can mount the same filesystem at once, and backends can use the files API beside them. They do not share a local disk. Unless marked verified, none of the following is verified by a test yet:
- Changes show up on other mounts in under a second (verified). Between a Mac and Linux, 30 of 30 writes, renames and deletes reached the other side within 0.78 s.
- No close-to-open guarantee. Opening a file right after another mount closed it can still show the old contents.
- Writers are coordinated per path, on a best-effort basis. A second mount that opens the same path for writing normally waits until the first writer closes it. Two names of a hard-linked file, a rename during an open write, or a writer that loses its lock can still produce two writers at once, and nothing stops a client that ignores the coordination.
flockandfcntllocks are shared across Linux mounts.mmapwithMAP_SHAREDis coherent only within one mount.- Moving or removing a directory while another client writes into it is not supported, for mounts and the files API alike. When a write's file is moved away under it, the write fails with an error and the moved file keeps its data (verified). In a rarer case, the directory is renamed away and another directory renamed into its place between a write's check and its commit: the write can then replace the newcomer's file, and the moved file can lose its data. A file created while a mount removes its empty parent directory can end up stored but in no listing; it still counts against the quota.
Give each writer its own files, or coordinate writers outside the filesystem.
Not supported
- Changing a file's owner (
chown) to another user. - POSIX ACLs (
setfacl). - Device nodes, FIFOs and sockets. Creating a FIFO or a device fails (verified).
- Running setuid or setgid programs from a mount.
- File names that are not valid UTF-8, or longer than 255 bytes.
- Byte-level coherence between two writers of the same file, and a single order of metadata changes seen by every mount.
Durability
A file written, closed and synced is still there, byte for byte, in the
next mount (verified). The rest of this section describes how the service is
built; it is not yet verified by crash or fault-injection tests.
- The mount buffers writes and commits them to the service when a file is
closed or
fsynced. If a mount ends abnormally (its sandbox is killed or its session is revoked), writes not yet committed are lost. - When
fsyncorclosesucceeds, the file's data has been written to disk withfsyncon the server before the upload was acknowledged, and the file's entry has been committed to the database afterwards. - The service keeps one copy of file data, on one server's disk. Backups are the only other copy: if that disk is lost, changes made since the last backup are lost.
Service stage
mountable.io is in an early stage:
- One cell: the API and the storage run on one server, with their database on a second one.
- No high availability: if either server goes down, so does the service.
- Daily backups to separate cloud storage; restoring a backup has been rehearsed. To take a consistent backup, the service stops once a day until the backup is copied out. In October 2026 a whole backup run took under a minute; the pause grows with the data stored. What mounts see during the pause is not verified.
- No service-level agreement: no promised availability, recovery time or recovery point.
Quotas
Each filesystem has two quotas. By default and at most they are 100 GiB of
stored data and 1,000,000 entries (files, directories and links). One
account can own ten organisations, and one organisation can have up to
10,000 filesystems. Quotas are not added up across filesystems. Creating
another organisation or filesystem past those counts is refused; files
already stored stay available. The console and mountable fs usage show a
filesystem's usage against its own quotas.
An app can give each filesystem smaller quotas, an operation rate and its own monthly spending cap: see limits per end user.
With a saved payment method, downloads have no cap: you pay per GiB you download, and a spending cap you set is the only limit. Until a payment method is saved, downloads are limited to 10 GiB each UTC month. While an organisation is suspended for nonpayment, downloads are limited to one copy of what is stored (and at least 10 GiB). The number of creates, deletes and renames per minute is not limited, unless an app set an operation rate on the filesystem (limits per end user).
- Stored data. Space is reserved when an upload starts, so data not yet committed counts too. A write that would exceed the quota fails (verified); the exact error a program sees is not verified. Deleted data keeps counting for about a day. Data of a file that ever had a hard link keeps counting until the filesystem is deleted, even after every name is removed. Not verified.
- Entries are counted a few seconds behind, so the limit is soft and can be overshot slightly. At the limit, creating a new entry fails; replacing an existing one still works. Not verified.
- One file holds at most 9,999 chunks of up to 2 MiB, about 19.5 GiB. Not verified.
Known issues
- Renaming a directory that contains a hard-linked file fails. This is a bug in the underlying storage software, found by our tests.
- Moving a file or directory into a sibling directory whose name starts with
its own name, or anywhere beneath that sibling, fails with "Invalid
argument", for example
mv report report.d/. This is a bug in the underlying storage software; the fix is proposed upstream in seaweedfs#12337.
On macOS
A Mac mounts through the NFS client built into macOS, with nothing extra to install (Mount on a Mac). Everything above applies. These tips help you get the most out of it:
-
Files deleted or moved elsewhere are gone within a second (CLI 0.8.1). Their old paths answer "No such file or directory", like any missing file. Earlier CLIs answered "Stale NFS file handle" for a path the Mac had already used.
-
Every write is stored before it is confirmed. One stream writes about 7 MiB/s. Writes the service confirmed are always stored. A
writethat returns has handed the data to macOS; callfsyncor close the file to know it is stored. -
Writes count toward an operation rate, if one is set. macOS sends writes in 1 MiB pieces, and each piece is one operation, shared with creates, deletes, renames and every other mount. On a filesystem whose app set a rate of, say, 1,000 operations a minute, that is about 1,000 MiB a minute, or about 1,000 records a minute for a program that appends a record and calls
fsynceach time. Without a rate, the 7 MiB/s per stream above is the limit. -
Databases, logs and git work in the mount (CLI 0.6.1). SQLite works in its default rollback-journal mode (WAL falls back to it on the mount),
integrity_checkclean, and a 10,500-page-write run stayed clean. Each transaction creates and deletes its journal file, which counts toward an operation rate if the filesystem has one.gitran 100 commits withgit fsckclean. A file the service stores in more than about 8,000 pieces, such as a log that appends a record and callsfsynceach time or a file rewritten in small patches, keeps taking writes past the 9,999-piece limit: each write there also merges earlier pieces into one. Checked with 10,500 appends and 10,500 in-place rewrites, every byte read back. -
Merging is best effort. It pauses while the filesystem is above 80% of its storage quota, after one mount has merged a tenth of the quota in a day, or when the service is too slow to answer in time; a file that then reaches 9,999 pieces fails with "File too large". Merged data counts toward storage, downloads and spending caps like any other data.
-
Near that limit a file writes more slowly. Small patches went from about 330 writes a minute to about 75. A file written start to end runs at about a third of the usual speed past about 7.8 GiB, and reaches about 15 GiB in a day at the default quota, about 19.5 GiB at most.
-
Check errors in the program that writes. macOS reports a failed write (at a quota, at a spending cap or after the session is revoked) once, to the first
write,fsyncorcloseof that file by any program. If something else, such as a Finder preview, closes the file first, it gets the error and yourfsyncreturns success. Open the file withO_SYNCto get each write's error directly, and preferwritetommapfor data that matters: macOS does not always report errors from mapped writes. -
Call
fsyncbefore the mount is forced off. When a session is revoked or expires, the CLI crashes, or you unmount with a file open, data macOS had not sent yet is lost, and anfsyncrunning at that moment can still return success. -
Add
._*to your global gitignore. macOS keeps extended attributes and resource forks in._files beside your files, and other mounts and the Files API see them as ordinary files:mkdir -p ~/.config/git && echo '._*' >> ~/.config/git/ignoreIf
git config --global core.excludesFileprints a path, add the line to that file instead. -
Spotlight does not index the mount, as with any network volume.
-
Locks are per mount.
flockandfcntlcoordinate programs on the same Mac mount, not across mounts: open a database through one mount at a time, even on the same machine. -
Writer coordination covers one write at a time, not the whole time a file is open.
Platforms
The mountable CLI is built for Linux and macOS on x86_64 and arm64.
Mounting on Linux needs FUSE. Mounting on macOS needs CLI 0.6.0 or later
and nothing else; 0.6.1 keeps logs and files patched in place going past
9,999 writes.
| Platform | Mounting |
|---|---|
| Linux, x86_64 | verified: by the end-to-end tests and in E2B sandboxes |
| Linux, arm64 | limited verification: CLI 0.4.0 created a filesystem and tickets, mounted, wrote/read and remounted in a local Linux FUSE container (2026-10-15); other providers are not qualified |
| macOS 26, Apple Silicon | checked with CLI 0.6.0 on the owner's Mac (macOS 26.7.1) against the production service by our qualification runner (2026-10-22): installing through npm, PyPI and the install script, mounting without sudo, read-only and read-write sessions, unmounting, revocation and expiry with open files, session renewal, confirmed writes surviving a crash, a revocation and a forced unmount, the byte quota on writes and the spending cap on writes and reads, git, vim, sed -i, editors' atomic saves, hard links, symlinks, mmap, locks, the operation rate on creates, and dead mounts |
| Other macOS versions, Intel Macs | not verified |