Skip to content
Get packs

Guide · Open source

How to use Shardeum: clone, build and run a local test network

Updated · written with AI from the project's own documentation and checked against our catalogue data

Shardeum is an open-source, EVM-based blockchain platform that uses sharding, a model that splits the network's work across parts of the network. This guide walks you through the README's setup path: installing the prerequisites, building the code, running a 10-node local network and connecting MetaMask to it. It is written for developers who want a local test environment, not for end users of a finished app.

Shardeumshardeum/shardeum · ★ 31.2k · MIT

Quick start

  1. 1Install prerequisites. Install Node.js v18.19.1, npm v10.2.4 and Rust v1.74.1, following the setup page linked in the README.
  2. 2Clone and install. Clone the shardeum repository and run npm ci inside it.
  3. 3Set config and compile. Export LOAD_JSON_CONFIGS pointing to debug-10-nodes.config.json, then run npm run prepare.
  4. 4Start the network. Install the Shardus CLI globally and run shardus start 10.
  5. 5Start the JSON-RPC server. Clone json-rpc-server, run npm install and npm run start, then use http://localhost:8080.
  6. 6Connect MetaMask. Add a custom network with Chain ID 8082 and currency symbol SHM, and add your wallet to src/config/genesis.json for test tokens.

What you need before you install Shardeum

The README lists Node.js, npm, Rust and, optionally, Docker as prerequisites. It names specific versions, and Shardeum needs those versions to build and run. The README points to a separate setup page for environment details, so read that before continuing.

  • Node.js v18.19.1
  • npm v10.2.4
  • Rust v1.74.1
  • Docker (optional, for containerized deployment)

How do you install Shardeum from source?

Installation is clone-and-build. You download the repository, install its dependencies, set a configuration variable, then compile the project. Run the commands from a terminal inside the cloned folder.

  • Clone the repository and move into it.
  • Install dependencies with npm ci.
  • Set LOAD_JSON_CONFIGS to the full path of debug-10-nodes.config.json inside your local repo.
  • Compile the project with npm run prepare.
  • Install the Shardus CLI and update the archiver package.
git clone https://github.com/shardeum/shardeum.git cd shardeum npm ci export LOAD_JSON_CONFIGS=[full-path-to-your-local-shardeum-repo]/debug-10-nodes.config.json npm run prepare npm install -g @shardeum-foundation/tools-shardus-cli npm update @shardeum-foundation/archiver

How do you run a local Shardeum network?

The README starts a local network of 10 nodes with the Shardus CLI. The network runs on your own computer, so it is suited to testing rather than production use.

shardus start 10

How do you start the JSON-RPC server?

The JSON-RPC server is a separate repository. Clone it, install its packages, then start it. The README gives the default RPC URL as http://localhost:8080.

git clone https://github.com/shardeum/json-rpc-server.git cd json-rpc-server npm install npm run start

How do you connect MetaMask to your local network?

Install the MetaMask extension, then add a custom network using the values below. To receive test SHM tokens, the README asks you to add your wallet address and balance to src/config/genesis.json.

  • Network Name: Shardeum
  • RPC URL: http://localhost:8080
  • Chain ID: 8082
  • Currency Symbol: SHM
  • Block Explorer URL: http://localhost:6001/
"YOUR-WALLET-ADDRESS": { "wei": "200000000000000000000000000" },

How do you check the node and stop the network?

Two health endpoints report on a node. /is-alive returns 200 if the server is running, and /is-healthy currently behaves the same way. To stop the network and clean up its files, use the command below.

  • GET /is-alive returns 200 if the server is running.
  • GET /is-healthy is currently the same as /is-alive.
shardus stop && shardus clean && rm -rf instances

What people use it for

  • Testing an EVM-compatible decentralized app against a local 10-node network.
  • Reading the TypeScript code to study how a sharded blockchain is structured.
  • Evaluating whether an EVM chain with sharding fits a project's requirements.
  • Exercising unit tests with Jest, where src/index.ts is mocked.

Frequently asked questions

Is Shardeum free to use?

The repository is licensed under the MIT License, which the README states, and its LICENSE file has the details. The README does not discuss pricing for any hosted service, so this guide does not cover that.

What do I need to install Shardeum?

The README requires Node.js v18.19.1, npm v10.2.4 and Rust v1.74.1. Docker is optional and is listed for containerized deployment. Install these before cloning the repository.

How do I run Shardeum locally?

Clone the repository, run npm ci, set LOAD_JSON_CONFIGS, run npm run prepare, install the Shardus CLI, then run shardus start 10. The README describes this as a 10-node local network.

How do I connect MetaMask to Shardeum?

Add a custom network with RPC URL http://localhost:8080, Chain ID 8082 and currency symbol SHM. The README also says to add your wallet address to src/config/genesis.json to receive test tokens.

How do I stop Shardeum and clean up?

Run shardus stop && shardus clean && rm -rf instances. This stops the network, cleans its resources and removes the instances folder.

How does Shardeum compare to Ethereum, Hardhat or Polygon?

This source does not include a comparison. The README describes Shardeum as an EVM-compatible platform that uses sharding, so you would need to test it against those projects yourself before deciding.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Shardeum suits developers who want a local EVM test network and engineers studying sharded blockchain code in TypeScript. It is a poor fit for non-developers, or for anyone who needs production guarantees, because the README covers local development only and does not describe production deployment or audits.

Install options & downloads