> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/solana-foundation/anchor/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

<ParamField path="--skip-build" type="flag" default="false">
  Skip building the program in the workspace
</ParamField>

<ParamField path="--skip-lint" type="flag" default="false">
  Skip checking for safety comments ("CHECK") in the code
</ParamField>

<ParamField path="--ignore-keys" type="flag" default="false">
  Skip checking for program ID mismatch between keypair and `declare_id!`
</ParamField>

<ParamField path="--arch" type="enum" default="sbf">
  Architecture to use when building the program

  **Options:** `sbf`, `bpf`
</ParamField>

### Deployment Options

<ParamField path="--skip-deploy" type="flag" default="false">
  Skip deploying programs (use previously deployed programs)
</ParamField>

### Validator Options

<ParamField path="--validator" type="enum" default="surfpool">
  Validator type to use for local testing

  **Options:**

  * `surfpool`: Use Surfpool validator (default, faster)
  * `legacy`: Use Solana test validator
</ParamField>

### Advanced Options

<ParamField path="--env" type="array">
  Environment variables to pass into the Docker container
</ParamField>

<ParamField path="cargo_args" type="string">
  Arguments to pass to the underlying `cargo build-sbf` command (use `--` to separate)
</ParamField>

## Examples

### Basic Localnet

Start a local validator with automatic build and deployment:

```bash theme={null}
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):

```bash theme={null}
anchor localnet --skip-build
```

### Skip Deployment

Start fresh validator without deploying programs:

```bash theme={null}
anchor localnet --skip-deploy
```

### Use Legacy Validator

```bash theme={null}
anchor localnet --validator legacy
```

### Complete Skip (Restart Only)

Just restart the validator without build or deploy:

```bash theme={null}
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:

```bash theme={null}
solana config set --url localhost
```

Verify connection:

```bash theme={null}
solana cluster-version
solana balance
```

### Anchor Client (JavaScript/TypeScript)

```typescript theme={null}
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

```rust theme={null}
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

```bash theme={null}
anchor localnet
```

**Terminal 2:** Interact with programs

```bash theme={null}
anchor shell
```

or run your client application:

```bash theme={null}
ts-node client/main.ts
```

### Code Changes Workflow

1. Make changes to program code
2. Stop localnet (Ctrl+C)
3. Restart with rebuild:
   ```bash theme={null}
   anchor localnet
   ```

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

```bash theme={null}
# Terminal 1: Keep validator running
anchor localnet --skip-build --skip-deploy

# Terminal 2: Build and deploy
anchor build
anchor deploy
```

## Managing the Validator

### Start

```bash theme={null}
anchor localnet
```

### Stop

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

```bash theme={null}
# For Surfpool
killall surfpool

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

### Reset State

Stop the validator and restart:

```bash theme={null}
# Stop with Ctrl+C, then:
anchor localnet
```

Or manually:

```bash theme={null}
rm -rf test-ledger/
anchor localnet
```

## Logs and Monitoring

### View Logs

```bash theme={null}
# In another terminal
solana logs
```

Filter by program:

```bash theme={null}
solana logs <PROGRAM_ID>
```

### Monitor Transactions

```bash theme={null}
anchor logs
```

### Check Validator Status

```bash theme={null}
solana cluster-version
solana epoch-info
solana validators
```

## Ledger Data

Validator state is stored in:

```bash theme={null}
test-ledger/     # Legacy validator
.surfpool/       # Surfpool validator
```

These directories contain:

* Account data
* Transaction history
* Validator configuration

## Airdrop SOL

Get SOL for testing:

```bash theme={null}
solana airdrop 10
```

or from Anchor:

```bash theme={null}
anchor airdrop 10
```

or programmatically:

```typescript theme={null}
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

```bash theme={null}
# Start localnet in background
anchor localnet &

# Develop your client
cd client/
npm run dev
```

### Manual Testing

```bash theme={null}
# Start localnet
anchor localnet

# In another terminal, test manually
anchor shell
```

### Integration Testing

```bash theme={null}
# 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

<Tip>
  Use `anchor localnet --skip-build` when iterating on client code without changing programs to save time.
</Tip>

<Info>
  The validator runs in the foreground. Keep the terminal open or run it in a terminal multiplexer like `tmux` or `screen`.
</Info>

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

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

## See Also

* [anchor test](/cli/test) - Run automated tests
* [anchor build](/cli/build) - Build programs
* [anchor deploy](/cli/deploy) - Deploy to any cluster
* [anchor shell](/cli/shell) - Interactive shell for testing