ADAMANT IPFS Node v0.1.0: A File Delivery Mesh You Can Run Yourself

Content-addressed storage, bounded disk usage, replication and repair — now packaged as an open-source service for your application.

A file upload is only the beginning. Your application still has to deliver those bytes to another person, keep enough copies, recover from a failed node, and avoid turning a finite disk into an unlimited promise.

Today we are releasing ADAMANT IPFS Node v0.1.0: the first tagged release and the first published container image of our self-hosted file-delivery service. It brings content addressing, a REST API, controlled peer-to-peer delivery, storage policies, replication, repair, and health checkpoints into one Node.js application.

ADAMANT Messenger already uses the service for attachments. With this release, the same infrastructure is easier for other developers and operators to evaluate, deploy, and adapt to their own applications.

Run the nodes. Choose the storage policy. Give your application a file identifier it can carry anywhere in your mesh.

A useful foundation for application-owned files

The integration starts with two straightforward actions: upload a file through POST /api/file/upload, then retrieve it through GET /api/file/:cid.

The returned content identifier, or CID, is derived from the content rather than the server address. Your application can pass that identifier to a recipient without deciding which machine should serve the file. A node can stream its local copy or retrieve the content from the configured peers that should hold it.

This is a natural fit for messenger attachments, immutable application media, and services whose clients already exchange content identifiers. In ADAMANT Messenger, the client uploads an encrypted attachment, carries its CID inside a message, and the recipient fetches it through their node. Encryption belongs to the client protocol; the storage service handles the bytes it receives. The reference deployment guide explains that separation.

A mesh with explicit operating rules

The node is built directly with Helia and libp2p. It runs an embedded IPFS stack alongside its HTTP API, with TCP transport, Noise encryption for peer connections, and Yamux stream multiplexing.

Operators configure the peer set. Rendezvous hashing ranks holders for each CID, so nodes with the same membership can derive the same placement. Age-based tiers let a deployment reduce the target number of copies as a file grows older. A resumable repair cycle checks for missing copies and attempts to restore the intended placement when content remains recoverable.

This combines placement and repair with the service that receives and delivers files. Teams building around a known, mutually configured set of nodes can run those functions without assembling an additional pin-orchestration service.

Finite disks deserve a real policy

Storage controls are part of the intake path. Disk reserves, aggregate request limits, file limits, and concurrent-transfer admission help the node refuse work it cannot safely accept. Optional temporary uploads can expire after a TTL; garbage collection uses watermarks and the lifecycle registry to reclaim eligible data.

Confirmed content stays protected. When confirmed files occupy the available capacity, admission limits matter: bounded storage does not mean silently deleting files that the policy says must remain durable. Operators choose the retention and replication policy, provision capacity, and monitor the results.

That is a practical benefit for self-hosting: storage behaviour can be inspected and configured, including what happens when a deployment runs short of space.

Reliability that looks beyond an open connection

The release includes recent fixes for a subtle mesh failure: a TCP connection can remain present while application streams stop working. Earlier peering logic could see a connected peer and leave a stalled session untouched.

PR #40 adds liveness checks and reactive session recovery. PR #42 strengthens that path further: concurrent recovery operations are coalesced, failed streams can trigger a reset without being vetoed by a successful ping, and placement can retry once on a fresh connection.

A connection can be alive while file delivery is stuck. Recovery needs to respond to the operation that actually failed.

Health reporting follows the same idea. GET /api/node/health exposes starting, ready, stale, or degraded, together with a persisted checkpoint height and membership information. The height advances when the required checks pass and freezes when they fail; heights are comparable only within the same membership version.

Operators should read that state, not just HTTP 200. Optional repair-backlog grace can tolerate a configured number of unsuccessful repair cycles, while the backlog and cycle results remain visible to monitoring. The default grants no grace.

Better integration with desktop and Tor clients

v0.1.0 also includes the desktop and Tor CORS work from PR #45, PR #47, and PR #48. Operators can explicitly allow the desktop app://. origin and appropriate onion origins, including the opaque null origin some Tor Browser requests send.

Upload and admission failures now include stable machine-readable error codes. A client can distinguish rate limiting, concurrency limits, insufficient storage, replication-quorum failures, and timeouts without parsing prose. These details help applications show a useful next step when a transfer fails.

CORS remains a browser compatibility control. Deployments still need the authorization and exposure policy appropriate to their application.

A release you can deploy and keep

The public container is available for linux/amd64 and linux/arm64:

docker pull ghcr.io/adamant-im/ipfs-node:0.1.0

The image runs as an unprivileged user and carries an SBOM and build-provenance attestation. Configuration is mounted separately at /app/config.json5. A single /data volume holds the blockstore, datastore, peer identity, pin set, lifecycle registry, repair cursor, and health checkpoint, keeping the persistent state together across container replacement.

The release publication pipeline re-pulls and smoke-tests both architectures. Its checks exercise startup, readiness, upload and download, clean shutdown, and preservation of content and peer identity across replacement.

For evaluation, start with docker/config.example.json5, which joins no network, and follow the Docker guide. The production template contains ADAMANT's peer list; your own deployment should define its own peers and browser origins. Keep the HTTP service behind a correctly configured HTTPS reverse proxy.

Choose the architecture with its boundaries in view

The configured topology avoids public DHT announcements and public gateway routing, reducing public exposure of content-routing metadata. It does not make a deployment anonymous or confidential by itself. The service does not encrypt stored files; uploads and downloads are unauthenticated by design. Applications that require confidentiality or authenticated access must supply those controls above the storage layer.

There is no public IPFS interoperability, IPNS, public gateway, or Kubo-compatible API in this release. Content stored here is not announced to the public network, and content held only by public peers cannot be retrieved through this node. Uploader-signed deletion, dynamic peer discovery, and traffic accounting remain open work.

For a known peer set and content-addressed application delivery, these choices form a focused operating model. For public IPFS participation, a dynamic fleet, or S3-style identity and access controls, read the comparison guide before choosing your storage architecture.

Start with one node. Build the mesh your application needs.

v0.1.0 gives developers a concrete starting point: a versioned service, public container images, documented REST behaviour, persistent storage state, and operational controls for a configured file-delivery mesh.

Explore the use cases, follow the quick start, and inspect the release notes. The GPL-3.0 source is open, and contributions are welcome.

Implementation references: release PR #38, documentation and distribution PR #35, and the reliability and client-integration PRs linked above.

ADAMANT IPFS Node v0.1.0: A File Delivery Mesh You Can Run Yourself was originally published in ADAMANT on Medium, where people are continuing the conversation by highlighting and responding to this story.