ADAMANT IPFS NodeSelf-hosted content-addressed file storage

A self-hosted IPFS storage node for application file delivery, with bounded disk usage, deterministic replication, repair, health checkpoints, and a REST API.

Quick start

What it is

Compare alternatives

View on GitHub

REST API for files

Upload multipart files over HTTP and read them back by CID as a streamed attachment. Lifecycle status, upload policy, and storage metrics are readable without an API key; administrative routes require one.

API overview

Controlled peer topology

Nodes talk over TCP with Noise and Yamux and run only identify and ping. There is no DHT, no mDNS, no relay, and no public gateway routing, which reduces public exposure of content-routing metadata without making a deployment private, anonymous, trustless, or censorship-proof.

Architecture

Bounded storage lifecycle

Scheduled garbage collection releases unconfirmed uploads once they outlive their TTL, and evicts down to the low watermark when the blockstore passes the high watermark or free space falls into the disk reserve.

Storage lifecycle

Deterministic placement

Rendezvous hashing ranks holders for every CID, so every node derives the same holder set without negotiating it. Age-based tiers ask for fewer copies as a file gets older.

How copies are placed

Repair and health checkpoints

A scheduled repair cycle restores missing copies in bounded passes. The health endpoint reports a monotonic checkpoint height that advances only when every prerequisite passes, including peer attestations when they are required.

Monitoring and health

Rate limits and admission control

Per-endpoint address-based rate limits cover upload, pin, and read. Admission control bounds concurrent uploads and downloads, keeps a per-client download share, and refuses a request before any block is written.

Security and privacy

Container and source distribution

Run the node as a container with one data volume and a mounted JSON5 configuration file, or build and run it from source on Node.js 24 under a process manager.

Run with Docker

Who it is for

Applications that upload user files and fetch them back by CID over HTTP
Developers who want a REST API instead of embedding an IPFS client library in every client
Service operators who need bounded disk usage, explicit replication, and an operational health signal
Self-hosters who want file storage on their own hardware, under their own configuration and peer list

Where it is not the right tool

Publishing content to the public IPFS network. The node runs no DHT, no public gateway, and no IPNS
Fetching arbitrary CIDs from the public network. Retrieval is limited to the configured peer set
Orchestrating an existing Kubo fleet. This is a standalone Helia service, not a Kubo API and not a cluster controller
Anonymity or censorship resistance. A controlled topology reduces public exposure of content-routing metadata; it does not make a deployment private, anonymous, trustless, or censorship-proof

See Comparison for how the node relates to Kubo, IPFS Cluster, and object storage.

Adopters

ADAMANT Messenger runs this node in production for attachment delivery, and its deployment is the reference for the defaults shipped in the repository. The node itself is a general-purpose service: the messenger is one adopter, not the reason the project exists. See ADAMANT Messenger for what that deployment configures and why.

Quick links

Quick start — get a node answering requests
Docker — container image, volume, and configuration mount
Configuration — every option, default, and validation rule
API overview — endpoint classes, authentication, and status codes
Storage lifecycle — admission, garbage collection, replication, and repair
Monitoring and health — health states, checkpoint height, and metrics