Skip to main content


The Codex project aims to create a decentralized durability engine that allows persisting data in p2p networks. In other words, it allows storing files and data with predictable durability guarantees for later retrieval.

WARNING: This project is under active development and is considered pre-alpha.

License: ApacheLicense: MITStability: experimentalCICodecovDiscord

Build and run

For detailed instructions on preparing to build nim-codex see Building Codex.

To build the project, clone it and run:

make update && make

The executable will be placed under the build directory under the project root.

Run the client with:


CLI options

build/codex --help

codex [OPTIONS]... command

The following options are available:

--config-file Loads the configuration from a TOML file [=none].
--log-level Sets the log level [=info].
--metrics Enable the metrics server [=false].
--metrics-address Listening address of the metrics server [=].
--metrics-port Listening HTTP port of the metrics server [=8008].
-d, --data-dir The directory where codex will store configuration and data..
-i, --listen-addrs Multi Addresses to listen on [=/ip4/].
-a, --nat IP Addresses to announce behind a NAT [=].
-e, --disc-ip Discovery listen address [=].
-u, --disc-port Discovery (UDP) port [=8090].
--net-privkey Source of network (secp256k1) private key file path or name [=key].
-b, --bootstrap-node Specifies one or more bootstrap nodes to use when connecting to the network..
--max-peers The maximum number of peers to connect to [=160].
--agent-string Node agent string which is used as identifier in network [=Codex].
--api-bindaddr The REST API bind address [=].
-p, --api-port The REST Api port [=8080].
--repo-kind backend for main repo store (fs, sqlite) [=fs].
-q, --storage-quota The size of the total storage quota dedicated to the node [=8589934592].
-t, --block-ttl Default block timeout in seconds - 0 disables the ttl [=$DefaultBlockTtl].
--block-mi Time interval in seconds - determines frequency of block maintenance cycle: how
often blocks are checked for expiration and cleanup.
--block-mn Number of blocks to check every maintenance cycle. [=1000].
-c, --cache-size The size in MiB of the block cache, 0 disables the cache - might help on slow
hardrives [=0].
--persistence Enables persistence mechanism, requires an Ethereum node [=false].
--eth-provider The URL of the JSON-RPC API of the Ethereum node [=ws://localhost:8545].
--eth-account The Ethereum account that is used for storage contracts [=EthAddress.none].
--eth-deployment The json file describing the contract deployment [=string.none].
--validator Enables validator, requires an Ethereum node [=false].
--validator-max-slots Maximum number of slots that the validator monitors [=1000].

Available sub-commands:

codex initNode

Example: Running two Codex clients

For more information please see Codex Two-Client Test.

Interacting with the client

The client exposes a REST API that can be used to interact with the clients. These commands could be invoked with any HTTP client, however the following endpoints assume the use of the curl command.

For more information about API endpoints please see


Connect to a peer identified by its peer id. Takes an optional addrs parameter with a list of valid multiaddresses. If addrs is absent, the peer will be discovered over the DHT.


curl "<PEER ID HERE>?addrs=/ip4/"


Download data identified by a CID.


curl<CID>/network -o <OUTPUT FILE>


Upload a file, upon success returns the CID of the uploaded file.


curl -X POST -H "content-type: application/octet-stream" -H "Expect: 100-continue" -T "<FILE PATH>"


Get useful node info such as its peer id, address, and SPR.