A file is chunked into pieces of up to 256 KiB. Each piece becomes a raw block whose CID is the SHA-256 of its bytes (CIDv1, the bafkrei… form). A file that fits in one piece is that one raw block. That is why small icons in metadata look like ipfs://bafkreie6wls…. A larger file gets a root node in DAG-PB encoding (bafybei…), the UnixFS format. The root lists the pieces in order, with up to 174 links per node in a balanced tree. Both the daemon and the SDK build the tree with the same parameters (balanced layout, raw leaves, CIDv1, 256 KiB chunks), so the same bytes get the same CID whichever side chunks them.

DAG-PB is compact and carries almost no metadata: a node is a byte payload plus links. This is on purpose. The IPFS blocks of a file hold no filename, MIME type or size. A File block in a document may carry a display name beside the link. The daemon serves the bytes as application/octet-stream, and the client detects the type. File data is not signed. Its integrity comes from the hash alone, and its authorship from the signed blob that links to it.

The daemon indexes a DAG-PB node only far enough to record its links (dagpb/<name> or dagpb/chunk), so that visibility can flow down to the pieces. Raw leaves are stored but never indexed.

Blocks: Image, Video and File blocks hold their content in link as ipfs://<cid> (see blocks). An image in a comment works the same way.

Document metadata: icon, cover, thumbnail and seedExperimentalLogo are ipfs:// URLs, and so is a profile icon.

Schemas: schemaDefinition points at a schema blob by ipfs://<cid>. That blob is DAG-CBOR and is not a file. It is fetched through the same gateway.

A typed attribute uses the ipfs-url schema type to say "this value is a file reference".

A file block has no visibility of its own. When it is first stored it is treated as private. It becomes public as soon as any public blob links to it, directly or through another DAG-PB node. The indexer passes visibility along every link type into DAG-PB and raw blocks. So a public document's image and all of its chunks are public, and a private document's image stays private. If the only document linking a file is deleted or made private, the file follows.

This surprises people: a file uploaded on its own is not public. Publishing the blocks stores them, and the uploader can fetch them back. But a gateway in public-only mode answers 404 with "blob … is not public" until a published document, comment or profile references the ipfs:// URL. This rule stops a Seed node from acting as anonymous public file hosting. Link the file from something public, and it appears.

Every daemon serves files on its HTTP port, and every site proxies /ipfs/* on its domain straight to its daemon:

Responses carry ETag: <cid> and Content-Type: application/octet-stream. The client works out the file's real type. Cache-Control is public, max-age=29030400, immutable (about 336 days) when the daemon can prove the blob is public, and private, max-age=29030400, immutable otherwise, so shared caches and CDNs never keep private content. An Authorization: Bearer header from a signed-in web session lets the daemon serve a private file to a reader who may see its space.

There are two limitations. First, without the -public-only flag a daemon serves any blob it holds to anyone who knows the CID, and both POST routes are open to anyone who can reach the port. The Seed app's daemon binds all interfaces, so keep its HTTP port off untrusted networks. Second, on a hosted site the proxy forwards every method on /ipfs/* to the daemon, so the upload routes are reachable from the internet. An upload stays private until something public links it, but it still uses disk. As of September 2026 the compose template in this repository does not pass -public-only to the site daemon. So a hosted site's gateway serves a private blob to whoever presents its CID. Operators who want the stricter behaviour add the flag; see self-hosting.

Public IPFS gateways such as ipfs.io cannot find content published only on Seed. Seed nodes do not advertise blocks to the IPFS DHT (see Network). An https://ipfs.io/ipfs/<cid> link works only for content someone pinned there separately.

The web app adds two routes on top of the raw gateway. GET /hm/api/file/<cid> streams the daemon's /ipfs/<cid> with Range forwarded and the visitor's session cookie turned into a bearer token, so private files render for signed-in readers on hosted sites. GET /hm/api/image/<cid>?size=S|M|L|XL returns a PNG resized to at most 120, 650, 1600 or 4000 pixels wide (default M; GIFs pass through untouched). It caches the result on disk only when the daemon says the source is public. Every icon, cover and inline image on a rendered page goes through the image route. Downloads and videos go through the file route.

There are two ways to get a file into the network. Both produce the same CIDs:

Ask a daemon to chunk it: POST /ipfs/file-upload. The Seed app does this against its own local daemon for every drag-and-drop, paste and web-import.

Chunk it yourself and publish the blocks: the SDK's fileToIpfsBlobs (one file) or filesToIpfsBlobs (several, sharing a block store) returns the root CID and every block with its CID. Hand them to PublishBlobs on any site. The web app, the CLI and Seed Agents all use this path, because none of them can reach a daemon's upload route on a hosted site. Send each block with its SHA-256 CID. The daemon hashes a blob published without an explicit CID with BLAKE2b, and that CID would not match the links pointing at it (see Signed Blobs).

A single PublishBlobs request has a message-size limit of a few megabytes, so a large file is published in several requests. The agents runtime batches at 3 MiB. The daemon's own upload route accepts up to 150 MiB in one request.

Drag a file or image into the editor, paste one, or use the block menu's Image, Video and File blocks. The Seed app uploads to its local daemon and inserts the ipfs:// link. Space and document settings upload icons, covers and logos the same way. Files render from the local daemon's gateway, so they are available offline once synced. The maximum upload is 150 MiB. The agents memory tab has a "Publish to IPFS" action for a memory file, with the same "not public until linked" caveat.

seed-cli document create -f page.md resolves file:// links in image blocks and in icon, cover and logo metadata. It chunks each file with the SDK, publishes the blocks with the document, and turns the links into ipfs:// URLs. seed-cli profile set --icon ipfs://<cid> accepts only an already-published CID. seed-cli document cid <cid> fetches a block decoded as DAG-JSON through the site's GetCID, and seed-cli blob get ipfs://<cid> reads a DAG-CBOR blob and checks its signature and schema. There is no standalone upload command. Publish files as part of a document. See the CLI reference.

resolveFileLinksInBlocks(nodes, loader) replaces file:// links in a block tree with published ipfs:// links and returns the blobs to publish beside the document. hasFileLinks(nodes) tells you whether you need it. For reading, build URLs from the site: ${base}/ipfs/${cid} for bytes, ${base}/hm/api/image/${cid}?size=L for a resized image. The SDK guide has the full surface.

On any site: GET /ipfs/<cid> and GET /ipfs/<cid>.dagjson (the daemon's gateway, proxied), GET /hm/api/file/<cid>, GET /hm/api/image/<cid>?size=…, GET /api/GetCID?cid=… (returns {value} decoded), and POST /api/PublishBlobs with {blobs: [{cid, data}]} to store blocks you chunked yourself. On a daemon you control, POST /ipfs/file-upload and POST /ipfs/<cid> as above. The web API guide documents request and response shapes.

Seed Agents address files with their two verbs. read of ipfs://<cid> fetches a file into the agent's memory. For a DAG-CBOR object it returns the decoded value with its signature and schema check. write to ipfs:// publishes from exactly one source: options.fromPath for a memory file, options.fromAttachment for a file the user attached to the chat, or a JSON object in content (optionally validated against a schema and signed). It needs the agent's publish grant and returns the CID and ipfs:// URL. The runtime chunks with the SDK and publishes in 3 MiB batches to the agent's configured site (hosted agents use https://hyper.media; the desktop's agent uses the app's daemon). The guides at ~/tools/write/ipfs and ~/tools/write/documents spell out the options. Agents follow the same rule as everyone else: an ipfs:// URL on its own displays nowhere. To show a file in chat, an agent references its memory path (![caption](~/memory/path.png)). To publish it for the world, the agent links the URL from a document or comment. External agents using the seed-cli skill publish files through document create -f as above. See using Seed from your own agent.