Appearance
Attachments
Drop a file onto a page, or paste one — on a rich page or a Markdown page. Images render inline; everything else becomes a link that downloads.
An image can also come from the /image menu item: upload one from the device, or give its address on the web. Select an image to give it a description, written as its alt text in the Markdown, for whoever cannot see it.
What happens to the bytes
The file's metadata — name, content type, size, who uploaded it, and which page it hangs on — is a row in the database. The bytes are stored separately, addressed by an identifier, never by the name you gave them.
That is deliberate. A user-supplied filename on a filesystem path is the classic directory-traversal hole, and ../../etc is a perfectly ordinary thing to call a file. The name never reaches the filesystem; it is used when the file is served back to you and when it is exported, and nowhere else.
Attachments are behind the page
An attachment is served only to somebody who may read the page it hangs on. It is not protected merely by the difficulty of guessing its id, which is the usual arrangement and the usual leak — a link pasted into a chat is then a permanent, unrevokable grant to everyone in the room.
Because access follows the page, moving a page or changing who may read it changes who may fetch its attachments, with no separate list to keep in step.
Size and what renders
Uploads are capped at 25 MB.
Only PNG, JPEG, GIF, WebP, AVIF, PDF and plain text are served inline; everything else is sent as a download. That allowlist is a genuine security boundary rather than a nicety — serving an uploaded text/html inline would run the uploader's script on the API's own origin, with your session cookie in reach. A blocklist is a list of the attacks somebody thought of.
SVG is deliberately absent. It is an image to a person and a scriptable document to a browser, and there is no way to serve it inline that is safe without sanitising it. SVGs upload and download; they do not render in the page.
Nothing garbage-collects a file that no block references any more, and that is deliberate: a block can come back through a revert or a page restore, and returning to a broken image is worse than keeping the bytes.
Quotas
A workspace can carry a limit on total stored bytes. An upload is refused before a byte is read, from its declared length, and then checked again against what actually arrived — the declared length is the client's claim, and the second number is the one that gets stored. See quotas and the audit log.
Where the files actually live
With the default PGlite store, the bytes go on disk under the data directory, in <NOTESFLOW_DATA>/files, spread over two levels of subdirectory so no single directory has tens of thousands of entries in it.
Attachments and an external Postgres
If you set NOTESFLOW_DATABASE_URL without also setting NOTESFLOW_DATA, the server has no data directory to write blobs into and would keep uploaded bytes in memory, lost when the process restarts. In production it refuses to start like that; in development it warns. Set NOTESFLOW_DATA to a persistent volume whenever you use an external Postgres (or NOTESFLOW_ALLOW_MEMORY_BLOBS=1 if losing uploads really is intended).
The storage interface is three methods wide, so moving attachments to S3-compatible storage is implementing it and changing one constructor rather than a rewrite.