storj/storj: the Go monorepo behind the Storj V3 network

What storj/storj is, and who the repository is actually for

The README describes Storj as an S3-compatible platform and suite of distributed applications for storing data in a secure and distributed manner: files are encrypted, broken into pieces, and stored across a global network of computers, with retrieval limited to the owner. That description covers the product. The repository is narrower than the product. Its top-level directories are satellite/, storagenode/, multinode/, cmd/, private/, shared/, certificate/, crashcollect/, installer/, scripts/, testsuite/, versioncontrol/ and web/. Those are the pieces an operator or a core contributor touches: the satellite coordinates the network, the storagenode is the daemon a storage provider runs, and multinode bundles several node processes behind one interface.

That layout tells you who the repo is for. It is not aimed at an application developer who wants object storage, because that person would use the S3 gateway or the uplink client library rather than this tree. It is aimed at people running infrastructure on the network and at people changing the network itself. The README's own framing supports this: the contributing section points to CONTRIBUTING.md for feedback, local builds and pull requests, and the start-using section points outward to the wiki rather than giving in-repo instructions.

Satellite, storagenode, uplink: the data flow the layout implies

The repository is a Go monorepo with a module path of storj.io/storj. The dependency list in go.mod is a fair map of what the network does at runtime: PostgreSQL drivers (github.com/jackc/pgx/v5, github.com/go-sql-driver/mysql), an embedded key-value store (github.com/dgraph-io/badger/v4), gogo/protobuf for wire messages, gorilla/mux and gorilla/schema for HTTP surfaces, go-oauth2 and coreos/go-oidc for identity, prometheus/client_golang for metrics, and cloud.google.com/go/storage and pubsub for integrations. A satellite is therefore not a single binary talking to a single database; it is a service that expects SQL, object storage and message plumbing around it.

The README states the storage model plainly: files are encrypted, split into pieces, and distributed. What the repository adds is the operational half. There is a certificate/ directory, which matches the node identity model, and a proto.lock file, which pins the protobuf contract between components. The practical consequence for anyone reading the code is that the interesting boundaries are protocol boundaries, not package boundaries. If you want to understand how a piece gets placed, you follow the protobuf definitions and the satellite code, not a single well-named package.

Installing and building storj/storj from source

The README does not give install commands. It links to the wiki, which hosts the documentation and tutorials, and names three pages: Using the Storj Test Network, Using the Uplink CLI and Using the S3 Gateway. Those are the pages to follow for a working setup. What the repository itself tells you is the build contract: go.mod declares go 1.25.10, so the toolchain must be at least that, and the Makefile is the entry point for local work.

The default Makefile target prints help rather than building anything, and it pulls in four included files. Running the help target is the fastest way to see which commands exist in your checkout:

make help

You should see a usage line and a list of targets grouped by section, drawn from Makefile.release.mk, Makefile.dev.mk, Makefile.test.mk and Makefile.tools.mk. The split matters: build and release targets are not in the same file as test targets, so a change to the release path does not touch the test path. The Makefile does not document what each target does beyond its one-line comment, so read the included file before running a target that writes artifacts.

A first real use is not a hello-world program. It is standing up the test network described in the wiki and pointing the Uplink CLI at it, or running the S3 Gateway against it. The README gives no flags, ports or environment variables for those steps, and inventing them would be wrong. Get them from the wiki page for the component you are running.

The versioning contract, and why it rules out normal Go consumption

The most useful paragraph in the README is the note on versioning. Storj practices semantic versioning for client libraries such as uplink, and explicitly does not practice it in this repo, because the repo is not intended to be used via Go modules. The README states there may be backwards-incompatible changes between minor and patch releases here.

Read that against the release list and the consequence is concrete. Releases v1.163.4, v1.163.5 and v1.163.6 are all patch-level bumps, and under the stated policy any of them could break an importer. If you pin storj.io/storj as a dependency, you are pinning a moving target and you own the breakage. The intended integration surface is elsewhere: the uplink library for clients, the S3 gateway for S3-speaking tools. Treating this module as a stable import is a misuse of the project, not a limitation the maintainers failed to fix.

The same note has a second effect. Because the repo is not a library, its public API is not a promise. Code in shared/ or private/ may be reusable in practice, but nothing in the README commits to keeping it stable, and the release cadence suggests it will change.

Licence and the CLA: AGPL-3.0 with a relicensing path

The repository is licensed AGPLv3. For anyone running a storage node or self-hosting a satellite, the operative question is whether the AGPL's network-use clause reaches their deployment, and the README does not answer that. It states the licence and nothing more, so the answer depends on your setup and belongs with your own counsel rather than with this article.

The contributor side is more explicit. The README asks contributors to sign Contributor License Agreement v2 so that the project can relicense the code under Apache v2 or other licences in the future. That is a real asymmetry: inbound contributions arrive under terms that permit relicensing, while the current outbound licence is AGPLv3. If you plan to contribute, know that you are granting that permission. If you plan to depend on the code, know that the licence you see today may not be the only one the project can apply to it later.

Where storj/storj is the wrong tool

Two cases stand out. The first is application development. If you want to store objects from a Go service, this repository is the wrong layer. The README points to the uplink library for client use and to the S3 gateway for S3-compatible access, and the versioning note tells you why importing this module directly is a bad idea. Reaching for storj.io/storj when you want a storage client is a category error.

The second is the single-node operator who wants a simple daemon. The presence of a multinode/ directory and of an installer/ directory suggests the project expects deployments where several node processes are managed together, and the go.mod dependency set suggests a satellite needs SQL and object storage around it. The README does not document a minimal single-binary deployment path, and it does not document rollback or downgrade behaviour at all. If you need a documented upgrade and rollback story before you deploy, this repository does not provide one, and you should establish that from the wiki and the release notes rather than assume it.

A third, softer case: anyone who wants a managed service. This repo is the software. Running it is your job.

Alternatives, and the actual difference in approach

The obvious comparison is MinIO, which is also S3-compatible object storage that you self-host. The difference is architectural rather than cosmetic. MinIO is a single software stack you run on servers you control, and the durability model is erasure coding across those servers. Storj's model, as the README describes it, is encryption plus fragmentation across a global network of independently operated computers, with satellites coordinating placement. That means Storj's availability depends on a population of third-party node operators, and your operational surface includes the economics and health of that population, not just your own hardware.

Against Backblaze B2, the split is the same shape. B2 is a hosted service from one provider with one API and one bill; Storj is software you can run yourself against a network, with an S3-compatible gateway in front if you want it. If your requirement is a single vendor with a support contract, neither this repository nor the network it builds is a substitute. If your requirement is that no single operator holds your data, the fragmentation model is the point, and the cost is that you are now responsible for running the coordinator.

Editorial conclusion

Adopt storj/storj if you are running storage nodes, a multinode deployment, or contributing to the network itself, and you accept that this repo is not a stable Go dependency. Do not adopt it as a library for an application: the README says the project does not intend the repo to be used via Go modules, and it warns of backwards-incompatible changes between minor and patch releases. Before you build anything, verify the current Go toolchain requirement in go.mod and read the wiki pages for the test network, Uplink CLI and S3 Gateway, because those, not the README, are where the usage instructions live.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. storj/storj on GitHub