docs.codex.storage/docs/index.mdx

---
sidebar_position: 1
description: Codex is building a decentralised durability storage engine
---

import { Badge } from '../src/components/Badge'


# Guides

> 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.

<Badge className="badge-margin" href="https://opensource.org/licenses/Apache-2.0" imgSrc="https://img.shields.io/badge/License-Apache%202.0-blue.svg" imgAlt="License: Apache"/>

<Badge className="badge-margin" href="https://opensource.org/licenses/MIT" imgSrc="https://img.shields.io/badge/License-MIT-blue.svg" imgAlt="License: MIT"/>

<Badge className="badge-margin" href="https://img.shields.io/badge/stability-experimental-orange.svg" imgSrc="https://img.shields.io/badge/stability-experimental-orange.svg" imgAlt="Stability: experimental"/>

<Badge className="badge-margin" href="https://github.com/codex-storage/nim-codex/actions/workflows/ci.yml?query=branch%3Amaster" imgSrc="https://github.com/codex-storage/nim-codex/actions/workflows/ci.yml/badge.svg?branch=master" imgAlt="CI"/>

<Badge className="badge-margin" href="https://codecov.io/gh/codex-storage/nim-codex" imgSrc="https://codecov.io/gh/codex-storage/nim-codex/branch/master/graph/badge.svg?token=XFmCyPSNzW" imgAlt="Codecov"/>

<Badge className="badge-margin" href="https://discord.gg/codex-storage" imgSrc="https://img.shields.io/discord/895609329053474826" imgAlt="Discord" />


## Build and run

For detailed instructions on preparing to build nim-codex see [*Building Codex*](https://github.com/codex-storage/nim-codex/blob/master/BUILDING.md).

To build the project, clone it and run:
```bash
make update && make
```

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

Run the client with:
```bash
build/codex
```


### CLI options

```
build/codex --help
Usage:

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 [=127.0.0.1].
     --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/0.0.0.0/tcp/0].
 -a, --nat                  IP Addresses to announce behind a NAT [=127.0.0.1].
 -e, --disc-ip              Discovery listen address [=0.0.0.0].
 -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 [=127.0.0.1].
 -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.
                            [=$DefaultBlockMaintenanceInterval].
     --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](https://github.com/codex-storage/nim-codex/blob/master/docs/TWOCLIENTTEST.md).


### 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 [api.codex.storage](https://api.codex.storage/).


#### `/api/codex/v1/connect/{peerId}`

Connect to a peer identified by its peer id. Takes an optional `addrs` parameter with a list of valid [multiaddresses](https://multiformats.io/multiaddr/). If `addrs` is absent, the peer will be discovered over the DHT.

Example:
```bash
curl "127.0.0.1:8080/api/codex/v1/connect/<PEER ID HERE>?addrs=/ip4/127.0.0.1/tcp/8071"
```


#### `/api/codex/v1/data/{id}/network`
Download data identified by a `CID`.

Example:
```bash
curl 127.0.0.1:8080/api/codex/v1/data/<CID>/network -o <OUTPUT FILE>
```


#### `/api/codex/v1/data`

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

Example:
```bash
curl -X POST 127.0.0.1:8080/api/codex/v1/data -H "content-type: application/octet-stream" -H "Expect: 100-continue" -T "<FILE PATH>"

```


#### `/api/codex/v1/debug/info`

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

Example:
```bash
curl 127.0.0.1:8080/api/codex/v1/debug/info
```