leo devnet

The leo devnet command launches and manages a local Aleo development network using snarkOS, providing a full-featured environment for testing Leo programs.

Syntax

leo devnet [OPTIONS]

Options

Network Configuration

--num-validators

number

default:4

Number of validator nodes to run.

--num-clients

number

default:2

Number of client nodes to run.

-n, --network

string

default:"testnet"

Network type: mainnet, testnet, or canary.

Storage Options

--storage

string

default:"./"

Ledger and log root directory.

--clear-storage

boolean

default:false

Remove existing devnet storage before starting.

--clean-only

boolean

default:false

Only clean devnet storage (ledgers, node data, logs) without starting.

snarkOS Configuration

--snarkos

string

Path to snarkOS binary. If not found, use --install to build it at this path.

--snarkos-features

string[]

Required features for snarkOS (comma-separated). Example: test_network

--snarkos-version

string

Required version of snarkOS. Defaults to latest version on crates.io.

--install

boolean

default:false

(Re)install snarkOS at the provided --snarkos path with --snarkos-features.

Port Configuration

--rest-port

number

Base REST port. Each node uses base + node_index.Default for validator 0: 3030

--node-port

number

Base node port. Each node uses base + node_index.

--bft-port

number

Base BFT port. Each node uses base + node_index.

--metrics-port

number

Base metrics port. Each validator uses base + node_index.

Consensus Options

--consensus-heights

string

Custom consensus heights (comma-separated). The test_network feature must be enabled.Can also be set via CONSENSUS_VERSION_HEIGHTS environment variable.

Display Options

--tmux

boolean

default:false

Run nodes in tmux (Unix only). Allows easy monitoring of individual nodes.

--verbosity

number

default:1

snarkOS verbosity level (0-4):

0: Error only
1: Warn
2: Info
3: Debug
4: Trace

Additional Options

-y, --yes

boolean

default:false

Skip confirmation prompts and proceed with devnet startup.

Examples

Start Default Devnet

leo devnet

Starts a devnet with:

4 validators
2 clients
Testnet configuration
REST endpoint at http://localhost:3030

Output:

🚀 Starting Aleo Devnet
──────────────────────────────────────────────
📊 Configuration:
  Validators:       4
  Clients:          2
  Network:          testnet
  Storage:          ./
  snarkOS:          /path/to/snarkos

🔌 Endpoints:
  Validator 0:      http://localhost:3030 (REST)
  Validator 1:      http://localhost:3031 (REST)
  Validator 2:      http://localhost:3032 (REST)
  Validator 3:      http://localhost:3033 (REST)

Do you want to proceed? [y/N]: y

🟢 Validator 0 started (PID: 12345)
🟢 Validator 1 started (PID: 12346)
🟢 Validator 2 started (PID: 12347)
🟢 Validator 3 started (PID: 12348)
🔵 Client 0 started (PID: 12349)
🔵 Client 1 started (PID: 12350)

✅ Devnet is running!
   Press Ctrl+C to stop.

Start with Custom Node Count

leo devnet --num-validators 6 --num-clients 4

Start with tmux

leo devnet --tmux

Each node runs in a separate tmux pane for easy monitoring:

# Attach to tmux session
tmux attach -t leo-devnet

# Navigate between panes
Ctrl+B then arrow keys

Start with Custom Storage

leo devnet --storage ./my-devnet

Clear Storage Before Starting

leo devnet --clear-storage

This deletes all existing ledger data. Use with caution.

Clean Storage Only

leo devnet --clean-only

Removes devnet storage without starting nodes.

Install and Use Specific snarkOS Version

leo devnet \
  --snarkos ./bin/snarkos \
  --snarkos-version 4.1.0 \
  --snarkos-features test_network \
  --install

This will:

Install snarkOS 4.1.0 with test_network feature
Save binary to ./bin/snarkos
Use it to start the devnet

Start with Custom Ports

leo devnet \
  --rest-port 4000 \
  --node-port 5000 \
  --bft-port 6000

Validator 0 will use:

REST: 4000
Node: 5000
BFT: 6000

Validator 1 will use:

REST: 4001
Node: 5001
BFT: 6001

And so on…

Start with Custom Consensus Heights

leo devnet --consensus-heights 0,100,200

Or via environment variable:

CONSENSUS_VERSION_HEIGHTS=0,100,200 leo devnet

Custom consensus heights require the test_network feature in snarkOS.

Start with High Verbosity

leo devnet --verbosity 3

Shows detailed debug logs from snarkOS.

Using the Devnet

Once running, use the devnet with Leo commands:

Deploy Programs

leo deploy \
  --broadcast \
  --devnet \
  --endpoint http://localhost:3030 \
  --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH

Execute Transactions

leo execute main 1u32 2u32 \
  --broadcast \
  --devnet \
  --endpoint http://localhost:3030 \
  --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH

Query Network State

leo query block latest \
  --endpoint http://localhost:3030 \
  --network testnet

Devnet Architecture

Validators

Validate and propose blocks
Participate in consensus
Maintain full ledger state
Expose REST API

Clients

Broadcast transactions
Query network state
Do not participate in consensus

Communication

Validator 0 ←→ Validator 1 ←→ Validator 2 ←→ Validator 3
     ↓              ↓              ↓              ↓
  Client 0 ←────→ Client 1

Storage Structure

./
├── validator-0/
│   ├── ledger/          # Blockchain data
│   └── logs/            # Node logs
├── validator-1/
│   ├── ledger/
│   └── logs/
├── validator-2/
│   ├── ledger/
│   └── logs/
├── validator-3/
│   ├── ledger/
│   └── logs/
├── client-0/
│   └── logs/
└── client-1/
    └── logs/

Default Private Keys

Devnet uses deterministic private keys:

# Validator 0 (primary test key)
APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH

# Validator 1, 2, 3... (derived keys)

These keys are for testing only. Never use devnet keys on mainnet.

Monitoring the Devnet

View Logs

# Tail validator 0 logs
tail -f validator-0/logs/node.log

# View all validator logs
tail -f validator-*/logs/node.log

Check Node Status

Query REST API:

# Get latest block
curl http://localhost:3030/testnet/latest/block

# Get latest height
curl http://localhost:3030/testnet/latest/height

# Get node status  
curl http://localhost:3030/testnet/node/status

View Metrics

If metrics are enabled:

curl http://localhost:9000/metrics  # Validator 0
curl http://localhost:9001/metrics  # Validator 1

Stopping the Devnet

Press Ctrl+C to stop all nodes:

^C
🛑 Shutting down devnet...
   Stopped validator 0 (PID: 12345)
   Stopped validator 1 (PID: 12346)
   Stopped validator 2 (PID: 12347)
   Stopped validator 3 (PID: 12348)
   Stopped client 0 (PID: 12349)
   Stopped client 1 (PID: 12350)
✅ Devnet stopped.

Troubleshooting

Port Already in Use

Failed to start validator 0: Address already in use

Solutions:

Stop existing devnet
Use different ports: --rest-port 4000
Kill processes using the port

snarkOS Not Found

snarkOS binary not found at path

Solutions:

Install snarkOS: --install --snarkos ./bin/snarkos
Provide correct path: --snarkos /path/to/snarkos

Nodes Not Connecting

Check:

Firewall allows local connections
Port configuration is correct
Node logs for connection errors

Storage Issues

Failed to initialize ledger

Solutions:

Clean storage: --clean-only
Use different directory: --storage ./new-devnet
Check disk space

Performance Tips

Reduce Nodes: Use fewer validators for faster consensus
SSD Storage: Use SSD for --storage directory
Lower Verbosity: Use --verbosity 0 for less logging
Dedicated Storage: Use separate disk for storage

Comparison with Devnode

Feature	`leo devnet`	`leo devnode`
Nodes	Multiple validators + clients	Single node
Consensus	Full BFT consensus	Instant block creation
Use Case	Realistic testing	Rapid development
Speed	Slower (consensus)	Faster (instant)
Resources	Higher	Lower

Use leo devnet for realistic testing and leo devnode for rapid iteration.

Get Started

Leo Language

CLI Commands

Development

Advanced

Documentation Index

​Syntax

​Options

​Network Configuration

​Storage Options

​snarkOS Configuration

​Port Configuration

​Consensus Options

​Display Options

​Additional Options

​Examples

​Start Default Devnet

​Start with Custom Node Count

​Start with tmux

​Start with Custom Storage

​Clear Storage Before Starting

​Clean Storage Only

​Install and Use Specific snarkOS Version

​Start with Custom Ports

​Start with Custom Consensus Heights

​Start with High Verbosity

​Using the Devnet

​Deploy Programs

​Execute Transactions

​Query Network State

​Devnet Architecture

​Validators

​Clients

​Communication

​Storage Structure

​Default Private Keys

​Monitoring the Devnet

​View Logs

​Check Node Status

​View Metrics

​Stopping the Devnet

​Troubleshooting

​Port Already in Use

​snarkOS Not Found

​Nodes Not Connecting

​Storage Issues

​Performance Tips

​Comparison with Devnode

​Next Steps

Build docs developers (and LLMs) love

Syntax

Options

Network Configuration

Storage Options

snarkOS Configuration

Port Configuration

Consensus Options

Display Options

Additional Options

Examples

Start Default Devnet

Start with Custom Node Count

Start with tmux

Start with Custom Storage

Clear Storage Before Starting

Clean Storage Only

Install and Use Specific snarkOS Version

Start with Custom Ports

Start with Custom Consensus Heights

Start with High Verbosity

Using the Devnet

Deploy Programs

Execute Transactions

Query Network State

Devnet Architecture

Validators

Clients

Communication

Storage Structure

Default Private Keys

Monitoring the Devnet

View Logs

Check Node Status

View Metrics

Stopping the Devnet

Troubleshooting

Port Already in Use

snarkOS Not Found

Nodes Not Connecting

Storage Issues

Performance Tips

Comparison with Devnode

Next Steps