Deploy a Local Testnet

Cross-platform setup script for running a Klever localnet on your machine. Works on Linux, macOS, and Windows.

Prerequisites

Docker Desktop 20.10+
- Linux: Install Docker Engine
- macOS: Docker Desktop for Mac
- Windows: Docker Desktop for Windows
Python 3.7+

Verify Python is installed:

python3 --version

Step 1 — Clone the Repository

Clone the repository to your machine:

git clone https://github.com/klever-io/kleverchain-localnet.git
cd kleverchain-localnet

Step 2 — Run the Setup

Run the one-command setup to generate keys, directories, and configuration files automatically:

# Linux/macOS
python3 setup.py setup-all

# Windows
python setup.py setup-all

This will automatically:

Check all requirements
Generate validator and wallet keys
Create necessary directories
Generate configuration files

Step 3 — Start the Localnet

Linux users: Before starting, grant permissions to the generated directories so Docker containers can access them:

sudo chown -R 999 .

# Linux/macOS
python3 setup.py start

# Windows
python setup.py start

Your local Klever testnet is now running.

Custom Configuration

You can configure the number of validators and the max token supply:

# Setup with 3 validators
python3 setup.py setup-all -n 3

# Setup with 3 validators and custom max supply
python3 setup.py setup-all -n 3 -s 10000000000000000

Available Commands

Setup

Command	Description
`setup-all`	Complete automated setup (keys + dirs + config)
`check-requirements`	Verify all dependencies are installed
`generate-keys -n <N>`	Generate keys for N validators
`generate-dirs -n <N>`	Create node directories
`create-localnet -n <N>`	Generate configuration files

python3 setup.py setup-all -n 3
python3 setup.py check-requirements
python3 setup.py generate-keys -n 3
python3 setup.py generate-dirs -n 3
python3 setup.py create-localnet -n 3

Container Management

Command	Description
`start`	Start Docker containers
`stop`	Stop Docker containers
`restart`	Restart Docker containers
`status`	Show container status
`logs`	Follow container logs
`logs --no-follow`	Print logs without following

python3 setup.py start
python3 setup.py stop
python3 setup.py restart
python3 setup.py status
python3 setup.py logs
python3 setup.py logs --no-follow

# Follow logs for a specific node
docker logs -f node-0

Cleanup

clean-all is destructive. It permanently deletes all keys, databases, logs, and configuration files.

# Remove generated configs only
python3 setup.py clean

# Remove everything (keys, dbs, logs, configs)
python3 setup.py clean-all

Troubleshooting: If clean-all fails with a permission error, run it with sudo:

sudo python3 setup.py clean-all

Project Structure

After running setup-all, the directory structure will look like this:

kleverchain-localnet/
├── keys/
│   ├── node-0/
│   │   ├── validatorKey.pem
│   │   └── walletKey.pem
│   ├── node-1/
│   │   ├── validatorKey.pem
│   │   └── walletKey.pem
│   └── walletKey.pem        # Root wallet
├── dbs/
│   ├── node-0/
│   └── node-1/
├── logs/
│   ├── node-0/
│   └── node-1/
├── config/
│   └── node/
│       ├── genesis.json
│       ├── nodesSetup.json
│       ├── api.yaml
│       ├── config.yaml
│       ├── enableEpochs.yaml
│       └── external.yaml
├── docker-compose.yaml
└── setup.py

Root Wallet

In addition to the per-node wallet keys, a root wallet (keys/walletKey.pem) is generated at the root of the keys/ directory. This wallet is pre-funded in genesis and is intended for general use — sending transactions, deploying contracts, testing — without needing to use a validator's wallet directly.

It has a fixed genesis balance of 1,000,000 KLV and 1,000,000 KFI, deducted from the total supply before distributing to validators.

Resetting the Localnet

To wipe all state and start fresh:

python3 setup.py clean-all
python3 setup.py setup-all