anchor localnet

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:

Builds all programs in the workspace (unless --skip-build)
Starts a local validator (Surfpool or legacy)
Deploys programs to the validator (unless --skip-deploy)
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 programOptions: 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 testingOptions:

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

Make changes to program code
Stop localnet (Ctrl+C)
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.

CLI Commands

Rust API

TypeScript API

​Overview

​Command Syntax

​Description

​Options

​Build Options

​Deployment Options

​Validator Options

​Advanced Options

​Examples

​Basic Localnet

​Skip Build

​Skip Deployment

​Use Legacy Validator

​Complete Skip (Restart Only)

​Validator Details

​Surfpool (Default)

​Legacy Validator

​Connecting to Localnet

​Solana CLI

​Anchor Client (JavaScript/TypeScript)

​Rust Client

​Development Workflow

​Interactive Development

​Code Changes Workflow

​Managing the Validator

​Start

​Stop

​Reset State

​Logs and Monitoring

​View Logs

​Monitor Transactions

​Check Validator Status

​Ledger Data

​Airdrop SOL

​Port Configuration

​Use Cases

​Client Development

​Manual Testing

​Integration Testing

​Comparison with anchor test

​Notes

​See Also

Build docs developers (and LLMs) love

Overview

Command Syntax

Description

Options

Build Options

Deployment Options

Validator Options

Advanced Options

Examples

Basic Localnet

Skip Build

Skip Deployment

Use Legacy Validator

Complete Skip (Restart Only)

Validator Details

Surfpool (Default)

Legacy Validator

Connecting to Localnet

Solana CLI

Anchor Client (JavaScript/TypeScript)

Rust Client

Development Workflow

Interactive Development

Code Changes Workflow

Managing the Validator

Start

Stop

Reset State

Logs and Monitoring

View Logs

Monitor Transactions

Check Validator Status

Ledger Data

Airdrop SOL

Port Configuration

Use Cases

Client Development

Manual Testing

Integration Testing

Comparison with anchor test

Notes

See Also