Skip to main content

​
Managing Localnet

Control your local XYZ Chain with xyz localnet commands.

​
Start Localnet

xyz localnet start

Starting XYZ localnet...

Initializing chain...
Creating test accounts...
Starting node...

Localnet Started!

RPC:  http://localhost:26657
REST: http://localhost:1317
gRPC: localhost:9090

Test Accounts:
  alice   xyz1alice...  1,000,000 XYZ
  bob     xyz1bob...    500,000 XYZ

Use 'xyz localnet stop' to stop the network

​
Options

FlagDescriptionDefault
--backgroundRun in backgroundfalse
--resetClear existing data firstfalse

​
Run in Background

xyz localnet start --background
Logs are written to ~/.xyz-localnet/node.log.

​
Fresh Start

Clear existing data and start fresh: 
xyz localnet start --reset

​
Check Status

xyz localnet status

Localnet Status: Running

Node:     PID 12345
Uptime:   2h 34m
Block:    1,234

Endpoints:
  RPC:  http://localhost:26657 ✓
  REST: http://localhost:1317  ✓
  gRPC: localhost:9090         ✓

Accounts:
  alice   xyz1alice...   998,500 XYZ
  bob     xyz1bob...     500,000 XYZ

Localnet Status: Stopped

No localnet is currently running.
Run 'xyz localnet start' to start one.

​
Stop Localnet

xyz localnet stop

Stopping XYZ localnet...

Node stopped (PID 12345)
Localnet stopped successfully.

Data preserved in ~/.xyz-localnet/
Run 'xyz localnet start' to resume.

​
Options

FlagDescriptionDefault
--cleanAlso remove all datafalse

​
Stop and Clean

Remove all data when stopping: 
xyz localnet stop --clean

​
View Logs

When running in background: 
# Follow logs
tail -f ~/.xyz-localnet/node.log

# Last 100 lines
tail -100 ~/.xyz-localnet/node.log

# Search for errors
grep -i error ~/.xyz-localnet/node.log

​
Lifecycle

┌─────────────────────────────────────────────────────────┐
│                   Localnet Lifecycle                    │
└─────────────────────────────────────────────────────────┘

   ┌──────────┐    xyz localnet start    ┌─────────┐
   │ Stopped  │ ───────────────────────▶ │ Running │
   └──────────┘                          └─────────┘
        ▲                                     │
        │           xyz localnet stop         │
        └─────────────────────────────────────┘

   State persists between stop/start (unless --reset or --clean)

​
Common Workflows

​
Development Session

# Morning: Start localnet
xyz localnet start --background

# Work...deploy contracts, test, etc.

# Evening: Stop localnet
xyz localnet stop

​
Quick Reset

# Something went wrong, start fresh
xyz localnet stop --clean
xyz localnet start

​
Check Health

# Is localnet running?
xyz localnet status

# Can I reach the RPC?
curl http://localhost:26657/status

# What block are we on?
curl http://localhost:26657/status | jq '.result.sync_info.latest_block_height'

​
Environment Integration

​
With Scripts

#!/bin/bash

# Ensure localnet is running
if ! xyz localnet status | grep -q "Running"; then
  echo "Starting localnet..."
  xyz localnet start --background
  sleep 5  # Wait for startup
fi

# Run tests
./run-tests.sh

# Optionally stop
# xyz localnet stop

​
With Make

.PHONY: localnet-start localnet-stop test

localnet-start:
	xyz localnet start --background

localnet-stop:
	xyz localnet stop

test: localnet-start
	./run-tests.sh

​
With Docker Compose

If you prefer Docker: 
version: '3'
services:
  xyz-localnet:
    image: xyz-chain:latest
    ports:
      - "26657:26657"
      - "1317:1317"
      - "9090:9090"
    volumes:
      - xyz-data:/root/.xyz
volumes:
  xyz-data:

​
Troubleshooting

Another process is using required ports:
# Find what's using port 26657
lsof -i :26657

# Kill it
kill -9 <PID>

# Or check for zombie localnet
xyz localnet stop
Check data directory permissions:
ls -la ~/.xyz-localnet/

# Fix if needed
chmod -R 755 ~/.xyz-localnet/
Check logs for errors:
cat ~/.xyz-localnet/node.log | tail -50
Often fixed by resetting:
xyz localnet start --reset
The node process may be stuck:
# Force stop
xyz localnet stop

# Kill any remaining processes
pkill -f xyzd

# Start fresh
xyz localnet start --reset

​
Advanced Configuration

​
Custom Genesis

To customize genesis parameters: 
# Stop localnet
xyz localnet stop

# Edit genesis
vim ~/.xyz-localnet/config/genesis.json

# Start with existing config
xyz localnet start

​
Custom Ports

Edit ~/.xyz-localnet/config/config.toml: 
[rpc]
laddr = "tcp://0.0.0.0:26657"

[p2p]
laddr = "tcp://0.0.0.0:26656"
And ~/.xyz-localnet/config/app.toml: 
[api]
address = "tcp://0.0.0.0:1317"

[grpc]
address = "0.0.0.0:9090"