Kubo: running an IPFS node from the command line

What Kubo is, and the problem it removes

Kubo is the first implementation of IPFS and, in the README's phrasing, the most widely used one today. It is a Go binary that runs an IPFS node as a network service. The problem it addresses is specific: you have files or data you want to address by content hash rather than by hostname, serve to peers, and retrieve back from anyone who has a copy, without running your own coordination server.

The opinionated part is the data model. Kubo uses UnixFS for files and directories, Bitswap and HTTP for verifiable transfer, and HTTP Gateways so an ordinary browser can fetch content without speaking the peer-to-peer protocol. That combination is what makes interoperability with other IPFS implementations possible; the README points to Helia for JavaScript and a longer list of implementations elsewhere.

Who it is for: engineers who want a daemon they can drive from a shell or an HTTP client, not a library they embed. If you are writing an application and want IPFS semantics inside your own process, a library implementation is a better fit than a node you have to supervise. Kubo is for the case where the node itself is the deliverable, or the thing your other services talk to.

The moving parts: daemon, CLI, gateway, RPC API

Everything in Kubo routes through one long-running process. The CLI talks to that daemon over its RPC API rather than doing the work itself, which is why `ipfs add` against a stopped node fails while `ipfs init` succeeds. The repository layout reflects this split: cmd/ holds the command definitions, client/ the code that speaks to the daemon, core/ the node itself, and repo/ the on-disk repository.

Four interfaces sit on top of the same node. The CLI is the interactive surface. The HTTP RPC API lets you control the daemon from another process; the README warns in the Docker Compose file that the API port includes admin operations and should not be remotely accessible. The HTTP Gateway serves content for browsers, in both trusted and trustless modes. Routing is handled by a Routing V1 client and server, with delegated routing documented in docs/delegated-routing.md.

Discovery happens at two scopes. On a LAN, nodes find each other over mDNS. Across the wider network, the Amino DHT handles discovery. There is also a FUSE mount, marked experimental in the README, that exposes /ipfs, /ipns and /mfs as local filesystems. Treat that as a convenience for inspection, not as a filesystem you build a workflow on top of.

Installing Kubo from a binary or the Docker image

The README does not inline install steps; it points at the official installation guide at docs.ipfs.tech/install/command-line/ and lists four routes: prebuilt binaries from dist.ipfs.tech or GitHub Releases, Docker, a package manager, or a build from source. Pick the binary route if you want the shortest path.

For containers, the official image lives at ipfs/kubo on Docker Hub. The README distinguishes three tag families: release images for production, master-latest developer previews, and staging images for arbitrary commits. Use a release tag in anything you care about.

docker pull ipfs/kubo:latest
docker run --rm -it --net=host ipfs/kubo:latest

The `--net=host` flag matters. The container needs to accept inbound swarm connections, and host networking is how the README's example gets there without mapping every port by hand. To customize the node, the README says to pass config with `-e` or mount scripts into /container-init.d.

The repository also ships a docker-compose.yaml, which is more explicit about exposure. It maps swarm on 4001 for both TCP and UDP, and binds the API on 5001 and the gateway on 8080 to 127.0.0.1 only. The comment in that file is blunt about why: the API port includes admin operations. If you change those bindings, you are changing the security posture, not just the port numbers.

A first real use: init, daemon, add, cat

The README's Quick Taste section is the shortest path to a working node. It starts by initializing a repository with a named profile:

ipfs init --profile=unixfs-v1-2025

Initialization generates a keypair and prints a peer identity, a string beginning with 12D3KooW. That identity is the node's name on the network; losing the repository loses it. Next, start the daemon in the background:

ipfs daemon &

The README's expected output is a single line, `Daemon is ready`. Only after that line appears will the CLI commands reach a node.

Adding content returns a CID, and the README's example pipes a string through `-q` to get just the hash:

echo "hello IPFS" | ipfs add -q

The documented result is bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa. Reading it back with `ipfs cat` returns the original string. The README closes the loop with a verification step: paste the CID into check.ipfs.network to confirm your node is actually announcing that content to the network. That check is worth running the first time, because a node that adds content locally but cannot reach peers looks identical from the CLI.

The README notes that `ipfs add --help` lists all import options, and links the command-line quick start for more.

Memory is the constraint that decides deployments

The README's system requirements are the least promotional part of the document and the part most likely to be ignored. Kubo recommends at least 6 GB of RAM and 2 CPU cores, and states that larger pinsets need more: roughly 1 GiB of RAM per 20 million items for reproviding to the Amino DHT.

The caution block is explicit about the failure mode. Systems below the recommended memory may see instability, frequent OOM errors or restarts, and a missing data announcement during the reprovider window. The consequence is not a slow node; it is data that becomes fully or partially inaccessible to other peers. That is a correctness problem disguised as a capacity problem, and it is the strongest argument against running Kubo on a small VPS because it happens to compile there.

For constrained hardware, the README points to docs/production/low-memory.md rather than pretending the default configuration will work. If your target is a Raspberry Pi or a 1 GB container, read that document before you size anything. The README also notes Kubo is highly parallel, so single-core machines waste the design.

One more operational detail worth knowing before you pin a lot of data: content blocking is a documented feature aimed at public node operators, described in docs/content-blocking.md. If you plan to run a gateway that other people use, that file is not optional reading.

Where Kubo is the wrong choice

Kubo is a daemon with a persistent repository, a DHT client, and a memory floor. If your application needs to compute a CID for a byte string and fetch it from a known peer, you do not need any of that. Helia, the JavaScript implementation the README lists alongside Kubo, is built for embedding in an application process. Choosing Kubo for an in-process use case means shipping a second binary, supervising it, and paying the memory cost for capabilities you never call.

The FUSE mount is a second place to be careful. The README labels it experimental. Mounting /ipfs and /ipns as local filesystems invites code that treats IPFS as a POSIX filesystem, with all the assumptions about random writes and rename semantics that content addressing does not satisfy. Use it to look at things; do not build a pipeline that assumes it behaves like ext4.

The gateway is a third. Serving content to browsers through a gateway is a supported mode, and the README covers trusted and trustless retrieval, but the README does not document gateway hardening, rate limiting, or abuse handling. If you expose port 8080 publicly, that is a decision you are making without guidance from this document.

Finally, the README does not document rollback. There is no described procedure for reverting a node to an earlier state after a bad upgrade, and the Docker Compose file's volume layout is the only hint about what to back up.

Maintenance, licensing, and upgrade cost

The repository is not archived, and the last push was on 2026-09-16. Releases arrive on a regular cadence: v0.43.0 on 2026-08-03, v0.43.0-rc2 on 2026-07-29, and v0.43.1 on 2026-09-15. The presence of release candidates before stable tags means there is a window to test an upgrade before it lands in the release image.

Upgrading is not free. The repository carries a CHANGELOG.md, and a node with a large pinset has a reprovider window that the README links to memory pressure. The Dockerfile ties the published image to the Go version parsed from go.mod, and CI lints that the default stays in sync, so image contents track the source rather than drifting.

Licensing needs care. The repository contains LICENSE, LICENSE-APACHE and LICENSE-MIT, and the metadata reports the licence as NOASSERTION, which means GitHub could not map the files to a single recognized identifier. Dual Apache and MIT licensing is a common arrangement for Go projects, but the presence of a third LICENSE file means you should read all three before relying on a summary. This is not legal advice; if the distinction matters to your organization, have counsel read the files.

Editorial conclusion

Adopt Kubo if you need a self-hosted content-addressed store with a gateway and an RPC API you can script against, and you can give it the 6 GB of RAM the README recommends. Do not adopt it for constrained hardware without reading docs/production/low-memory.md first, and do not expect the README to explain gateway hardening or pinning strategy. Verify your CID resolves through check.ipfs.network before you build anything on top of it.

Frequently asked questions

Official sources

1. ipfs/kubo on GitHub
2. Issues
3. Project website
4. README
5. Releases