Working with Devnet

A practical guide to Solana development environments—devnet for testing against the network, localnet for fast offline development, and transitioning to mainnet.

What You'll Learn

• When to use devnet vs local validator
• How to switch between environments
• Setting up Amman for local Metaplex development
• Best practices for transitioning to mainnet

Prerequisites

• Solana CLI installed
• A keypair configured

Development Environment Options

For Metaplex development, we recommend two environments:

Devnet: Network Testing Environment

Devnet is Solana's primary development network—use it when you need to test against real network conditions.

When to Use Devnet

• Testing RPC interactions and API calls
• Verifying transactions work on the network
• Integration testing with deployed programs
• Testing with other devnet-deployed contracts
• Sharing work with team members

Connecting to Devnet

# CLI
solana config set --url devnet

# MPLX CLI
mplx config rpcs set devnet

# Verify
solana config get

In code:

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

const umi = createUmi('https://api.devnet.solana.com')

Getting Devnet SOL

# CLI
solana airdrop 2

# MPLX CLI
mplx toolbox sol-airdrop 2

See Airdrop SOL for Development for more options.

Devnet Characteristics

Localnet: Fast Local Development

For rapid iteration, use a local validator. No network latency, unlimited SOL, and full control.

Option 1: Basic solana-test-validator

Quick and simple for basic testing:

# Start local validator
solana-test-validator

# In another terminal, switch to localhost
solana config set --url localhost

# Unlimited airdrops
solana airdrop 100

See Setup a Local Validator for the basic setup guide.

Option 2: Amman (Recommended for Metaplex)

Amman is Metaplex's local validator toolkit with powerful features:

• Auto-clone programs from mainnet/devnet
• Clone accounts with their data
• Amman Explorer for transaction inspection
• Mock storage for metadata testing
• Pre-made configs for Metaplex programs

Quick Amman Setup

# Install
npm install -D @metaplex-foundation/amman

# Create config file .ammanrc.js
# Start
npx amman start

Example: Amman Config for Token Development

Create .ammanrc.js in your project root:

const { LOCALHOST, tmpLedgerDir } = require('@metaplex-foundation/amman');

module.exports = {
  validator: {
    killRunningValidators: true,
    accountsCluster: 'https://api.mainnet-beta.solana.com',
    accounts: [
      {
        label: 'Token Metadata Program',
        accountId: 'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s',
        executable: true,
      },
      {
        label: 'MPL Core',
        accountId: 'CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d',
        executable: true,
      },
    ],
    jsonRpcUrl: LOCALHOST,
    commitment: 'confirmed',
    ledgerDir: tmpLedgerDir(),
    resetLedger: true,
    verifyFees: false,
  },
  relay: {
    enabled: process.env.CI == null,
    killRunningRelay: true,
  },
  storage: {
    enabled: process.env.CI == null,
    storageId: 'mock-storage',
    clearOnStart: true,
  },
};

See the Amman documentation for full configuration options and pre-made configs for Bubblegum, Candy Machine, and more.

When to Use Localnet

• Rapid development iteration
• Offline development
• CI/CD pipelines
• Testing without rate limits
• Debugging with full control
• When devnet is down or slow

Comparing Environments

Environment Management

Quick Switching

# Add to ~/.bashrc or ~/.zshrc
alias sol-dev='solana config set --url devnet'
alias sol-local='solana config set --url localhost'
alias sol-main='solana config set --url mainnet-beta'

In Applications

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

// config.js
const CLUSTER = process.env.SOLANA_CLUSTER || 'devnet'

const ENDPOINTS = {
  'devnet': 'https://api.devnet.solana.com',
  'localnet': 'http://127.0.0.1:8899',
  'mainnet-beta': process.env.MAINNET_RPC || 'https://api.mainnet-beta.solana.com',
}

export const umi = createUmi(ENDPOINTS[CLUSTER])

Separate Wallets

Always use different wallets for each environment:

# Create separate wallets
solana-keygen new --outfile ~/.config/solana/devnet.json
solana-keygen new --outfile ~/.config/solana/mainnet.json

# Configure with MPLX CLI
mplx config wallets add devnet ~/.config/solana/devnet.json
mplx config wallets add mainnet ~/.config/solana/mainnet.json

Mainnet-Beta: Production

When you're ready for production:

solana config set --url mainnet-beta

Recommended RPC Providers

For production, use a dedicated RPC provider:

• Helius
• QuickNode
• Triton

Migration Checklist: Dev to Mainnet

Before deploying to mainnet:

Code

• [ ] Remove hardcoded devnet addresses
• [ ] Environment-based cluster configuration
• [ ] Error handling for network failures
• [ ] Retry logic with exponential backoff
• [ ] Proper compute unit and priority fee handling

Testing

• [ ] All features tested on devnet
• [ ] Edge cases handled
• [ ] Localnet tests pass in CI

Infrastructure

• [ ] Dedicated RPC provider configured
• [ ] Monitoring and alerting set up
• [ ] Separate mainnet wallet with proper security

Common Patterns

Development Workflow

# 1. Start local development with Amman
npx amman start

# 2. Code and test locally (fast iteration)
# ... make changes ...

# 3. Test on devnet
solana config set --url devnet
npm test

# 4. Deploy to mainnet when ready
solana config set --url mainnet-beta

CI/CD Pipeline

# GitHub Actions example
- name: Start local validator
  run: |
    npx amman start &
    sleep 10

- name: Run tests
  run: npm test
  env:
    SOLANA_CLUSTER: localnet

Troubleshooting

"Connection refused" on localhost

Local validator isn't running:

# Check if running
pgrep -f solana-test-validator

# Start it
solana-test-validator
# or
npx amman start

Program not found on localnet

Programs must be loaded. Use Amman to auto-clone:

// .ammanrc.js
accounts: [
  {
    label: 'Token Metadata Program',
    accountId: 'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s',
    executable: true,  // This clones the program
  },
]

Devnet airdrop failing

Rate limited. Options:

• Wait and retry
• Use a web faucet
• Switch to localnet for unlimited SOL

Next Steps

• Amman documentation - Full Amman setup and configuration
• Setup a local validator - Basic local validator guide
• Getting SOL for development - Devnet SOL sources

FAQ

Do I need testnet?

For most Metaplex development, no. Devnet + localnet covers typical use cases. Testnet is mainly for validator operators and performance testing.

Can I transfer assets between devnet and mainnet?

No. Each cluster is completely separate. Tokens, NFTs, and programs exist independently on each network.

Why use Amman instead of solana-test-validator?

Amman automatically clones programs and accounts from mainnet/devnet, includes an explorer relay for debugging, and provides mock storage for metadata. It's purpose-built for Metaplex development.

How often does devnet reset?

There's no fixed schedule. Resets happen for maintenance. Never rely on devnet data persisting—it's purely for testing.