Localnet Development Setup

This guide shows how to set up a local Solana validator with cloned accounts for efficient development.

Why Use Localnet with Cloned Accounts?

Fast iteration: No rate limits, instant transactions
Cost-free: No SOL needed for testing
Real data: Clone actual accounts from devnet/mainnet
Offline development: Work without internet
Consistent state: Reset anytime with fresh state

Quick Start

1. Start Basic Localnet

# Simple localnet validator
solana-test-validator

# With reset on each start
solana-test-validator --reset

2. Start Localnet with Cloned Accounts

Clone important accounts (Token Program, System Program extensions, etc.):

solana-test-validator \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --clone ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL \
  --clone metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s \
  --reset

Common accounts to clone:

TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA - Token Program
ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL - Associated Token Program
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s - Metaplex Token Metadata

3. Clone Specific Program

To clone a deployed program from devnet:

# Clone program with all its data
solana-test-validator \
  --clone <PROGRAM_ID> \
  --url devnet \
  --reset

4. Clone with Custom Ledger Path

solana-test-validator \
  --ledger .anchor/test-ledger \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --reset

Development Workflow

Terminal 1: Start Validator

# Start with cloned accounts
solana-test-validator \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --clone ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL \
  --reset \
  --quiet

Terminal 2: Deploy Programs

cd starter_program

# Set to localhost
solana config set --url localhost

# Deploy programs
anchor deploy

# Get program IDs
anchor keys list

Terminal 3: Frontend

cd frontend

# Ensure .env.local points to localhost
cat .env.local
# NEXT_PUBLIC_SOLANA_RPC_HOST=http://localhost:8899
# NEXT_PUBLIC_SOLANA_NETWORK=localnet

# Start dev server
pnpm dev

Terminal 4: Watch Logs (Optional)

solana logs

Advanced Configuration

Full-Featured Localnet

solana-test-validator \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --clone ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL \
  --clone metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s \
  --bpf-program gARh1g6reuvsAHB7DXqiuYzzyiJeoiJmtmCpV8Y5uWC ./target/deploy/starter_program.so \
  --bpf-program CounzVsCGF4VzNkAwePKC9mXr6YWiFYF4kLW6YdV8Cc ./target/deploy/counter_program.so \
  --ledger .anchor/test-ledger \
  --reset \
  --quiet

Clone Specific Accounts

To clone a token mint or specific account:

solana-test-validator \
  --clone <MINT_ADDRESS> \
  --clone <TOKEN_ACCOUNT_ADDRESS> \
  --url mainnet-beta \
  --reset

Set Compute Unit Limits

solana-test-validator \
  --compute-unit-limit 1400000 \
  --reset

Testing with Localnet

Run Anchor Tests Against Localnet

# Start validator in another terminal first
solana-test-validator --reset

# Run tests
anchor test --skip-local-validator

Run Specific Test File

anchor test --skip-local-validator tests/cross_program.ts

Useful Commands

Check Validator Status

solana cluster-version
solana ping

Check Account Balance

solana balance

Request Airdrop (Localnet)

solana airdrop 100

List Programs

solana program show gARh1g6reuvsAHB7DXqiuYzzyiJeoiJmtmCpV8Y5uWC

Close Validator

# Just Ctrl+C in the terminal running solana-test-validator

Common Issues

Issue: “Address already in use”

# Kill existing validator
pkill -f solana-test-validator

# Or find and kill process
lsof -i :8899
kill -9 <PID>

Issue: “Program not found”

# Rebuild and deploy
anchor build
anchor deploy

Issue: “Transaction simulation failed”

# Check logs
solana logs

# Increase compute units if needed
solana-test-validator --compute-unit-limit 1400000 --reset

Issue: Stale data after changes

# Always use --reset flag
solana-test-validator --reset

Clone Strategy for Different Use Cases

For Token Operations

solana-test-validator \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --clone ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL \
  --reset

For NFT Development

solana-test-validator \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --clone ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL \
  --clone metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s \
  --url mainnet-beta \
  --reset

For Testing Real Protocols

# Example: Clone Jupiter program
solana-test-validator \
  --clone JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB \
  --url mainnet-beta \
  --reset

Performance Tips

Use –quiet: Reduces log spam
Use –reset: Ensures clean state
Clone only what you need: Faster startup
Use –ledger: Persistent data between restarts (without –reset)
Set compute limits: Prevent resource exhaustion

Integration with Anchor.toml

Update Anchor.toml for localnet:

[provider]
cluster = "localnet"
wallet = "~/.config/solana/id.json"

[test.validator]
url = "http://localhost:8899"

[[test.validator.clone]]
address = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

[[test.validator.clone]]
address = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"

Then simply run:

anchor test
# Automatically starts validator with cloned accounts

Best Practices

Always use –reset during active development
Clone accounts from mainnet for production-like testing
Clone from devnet for faster sync
Keep validator running during dev session
Restart validator after program changes
Use separate terminals for validator, deploy, frontend, logs
Check solana logs when debugging transactions

Quick Reference

# Start localnet
solana-test-validator --reset

# Set to localnet
solana config set --url localhost

# Deploy
anchor deploy

# Run tests
anchor test --skip-local-validator

# Watch logs
solana logs

# Stop validator
Ctrl+C (in validator terminal)

For more information: