anchor localnet

Start a local Solana validator with automatic program deployment

Overview

The anchor localnet command builds programs, starts a local Solana validator, deploys programs, and keeps the validator running for development and testing.

Command Syntax

anchor localnet [OPTIONS] [-- <CARGO_ARGS>...]

Description

This command:

1. Builds all programs in the workspace (unless --skip-build)
2. Starts a local validator (Surfpool or legacy)
3. Deploys programs to the validator (unless --skip-deploy)
4. Keeps the validator running until manually stopped

Unlike anchor test, the localnet command doesn’t run tests - it just provides a running local blockchain for manual testing and client development.

Options

Build Options

--skip-build · flag · default: "false"

Skip building the program in the workspace

--skip-lint · flag · default: "false"

Skip checking for safety comments (“CHECK”) in the code

--ignore-keys · flag · default: "false"

Skip checking for program ID mismatch between keypair and declare_id!

--arch · enum · default: "sbf"

Architecture to use when building the program

Options: sbf, bpf

Deployment Options

--skip-deploy · flag · default: "false"

Skip deploying programs (use previously deployed programs)

Validator Options

--validator · enum · default: "surfpool"

Validator type to use for local testing

Options:

• surfpool: Use Surfpool validator (default, faster)
• legacy: Use Solana test validator

Advanced Options

--env · array

Environment variables to pass into the Docker container

cargo_args · string

Arguments to pass to the underlying cargo build-sbf command (use -- to separate)

Examples

Basic Localnet

Start a local validator with automatic build and deployment:

anchor localnet

Output:

Build success
Starting local validator...
Validator started at http://localhost:8899
Deploying programs...
Deployed: my_program (Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS)

Localnet running. Press Ctrl+C to stop.

Skip Build

Start validator without rebuilding (faster when code hasn’t changed):

anchor localnet --skip-build

Skip Deployment

Start fresh validator without deploying programs:

anchor localnet --skip-deploy

Use Legacy Validator

anchor localnet --validator legacy

Complete Skip (Restart Only)

Just restart the validator without build or deploy:

anchor localnet --skip-build --skip-deploy

Validator Details

Surfpool (Default)

Features:

• Faster startup time (~2 seconds)
• Optimized for Anchor development
• Managed automatically
• Lower resource usage

RPC Endpoint: http://localhost:8899

WebSocket: ws://localhost:8900

Legacy Validator

Features:

• Standard solana-test-validator
• Full Solana CLI compatibility
• Advanced configuration options
• Suitable for complex testing

RPC Endpoint: http://localhost:8899

WebSocket: ws://localhost:8900

Connecting to Localnet

Solana CLI

Configure the CLI to use localnet:

solana config set --url localhost

Verify connection:

solana cluster-version
solana balance

Anchor Client (JavaScript/TypeScript)

import * as anchor from "@anchor-lang/core";

const connection = new anchor.web3.Connection(
  "http://localhost:8899",
  "confirmed"
);

const wallet = anchor.Wallet.local();
const provider = new anchor.AnchorProvider(connection, wallet);
anchor.setProvider(provider);

const program = anchor.workspace.MyProgram;

Rust Client

use solana_client::rpc_client::RpcClient;

let rpc_client = RpcClient::new("http://localhost:8899".to_string());
let version = rpc_client.get_version()?;
println!("Connected to: {}", version.solana_core);

Development Workflow

Interactive Development

Terminal 1: Run localnet

anchor localnet

Terminal 2: Interact with programs

anchor shell

or run your client application:

ts-node client/main.ts

Code Changes Workflow

1. Make changes to program code
2. Stop localnet (Ctrl+C)
3. Restart with rebuild:
   anchor localnet
   

Or, if you want to rebuild and redeploy without restarting the validator:

# Terminal 1: Keep validator running
anchor localnet --skip-build --skip-deploy

# Terminal 2: Build and deploy
anchor build
anchor deploy

Managing the Validator

Start

anchor localnet

Stop

Press Ctrl+C in the terminal running localnet, or:

# For Surfpool
killall surfpool

# For legacy validator
solana-test-validator --reset

Reset State

Stop the validator and restart:

# Stop with Ctrl+C, then:
anchor localnet

Or manually:

rm -rf test-ledger/
anchor localnet

Logs and Monitoring

View Logs

# In another terminal
solana logs

Filter by program:

solana logs <PROGRAM_ID>

Monitor Transactions

anchor logs

Check Validator Status

solana cluster-version
solana epoch-info
solana validators

Ledger Data

Validator state is stored in:

test-ledger/     # Legacy validator
.surfpool/       # Surfpool validator

These directories contain:

• Account data
• Transaction history
• Validator configuration

Airdrop SOL

Get SOL for testing:

solana airdrop 10

or from Anchor:

anchor airdrop 10

or programmatically:

await provider.connection.requestAirdrop(
  wallet.publicKey,
  10 * anchor.web3.LAMPORTS_PER_SOL
);

Port Configuration

Default ports:

• RPC: 8899
• WebSocket: 8900

These are typically configured in the validator and cannot be changed through anchor localnet directly.

Use Cases

Client Development

# Start localnet in background
anchor localnet &

# Develop your client
cd client/
npm run dev

Manual Testing

# Start localnet
anchor localnet

# In another terminal, test manually
anchor shell

Integration Testing

# Start localnet in detached mode
anchor localnet &
LOCALNET_PID=$!

# Run tests
ts-node tests/integration.ts

# Stop localnet
kill $LOCALNET_PID

Comparison with anchor test

Feature	anchor localnet	anchor test
Builds programs	✓	✓
Starts validator	✓	✓
Deploys programs	✓	✓
Runs tests	✗	✓
Keeps validator running	✓	✗ (unless —detach)
Use case	Manual testing, client dev	Automated testing

Notes

Use anchor localnet --skip-build when iterating on client code without changing programs to save time.

The validator runs in the foreground. Keep the terminal open or run it in a terminal multiplexer like tmux or screen.

Localnet data is ephemeral. When you stop the validator and restart, all account data is reset unless you preserve the ledger directory.

For persistent local testing across sessions, consider preserving the test-ledger/ or .surfpool/ directory.

See Also

• anchor test - Run automated tests
• anchor build - Build programs
• anchor deploy - Deploy to any cluster
• anchor shell - Interactive shell for testing