Managing Localnet

Start, stop, and monitor your local development network

Managing Localnet

Control your local XYZ Chain with xyz localnet commands.

Start Localnet

xyz localnet start

Output

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

Flag	Description	Default
--background	Run in background	false
--reset	Clear existing data first	false

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

Output (Running)

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

Output (Stopped)

Localnet Status: Stopped

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

Stop Localnet

xyz localnet stop

Output

Stopping XYZ localnet...

Node stopped (PID 12345)
Localnet stopped successfully.

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

Options

Flag	Description	Default
--clean	Also remove all data	false

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

Start fails with 'port in use'

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

Start fails with 'permission denied'

Check data directory permissions:

ls -la ~/.xyz-localnet/

# Fix if needed
chmod -R 755 ~/.xyz-localnet/

Node crashes immediately

Check logs for errors:

cat ~/.xyz-localnet/node.log | tail -50

Often fixed by resetting:

xyz localnet start --reset

Status shows running but can't connect

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"