How to test a Solana program locally with an AI coding agent

Short answer

Give the agent a local chain and a test command, never a funded mainnet key. Use in-process tests (LiteSVM or Mollusk) for fast feedback and anchor test on a local network such as Surfpool for end-to-end runs. Oh My Sol ships a pinned, offline Surfpool 1.7.0 chain with /chain, /airdrop, /account and /rewind, and checks finished work on a fresh copy of that chain.

Who it’s for
Developers who let an AI agent write or change a Solana program and want it tested on a local chain, not on devnet or mainnet.
Last checked
, against Oh My Sol 0.1.0

Which local testing tool should I use?

ToolWhat it isUse it for
LiteSVMAn in-process Solana VM for Rust, TS/JS or PythonFast unit and integration tests; the tightest loop for an agent
MolluskA Rust test harness that runs instructions in a minified SVM, with no validator runtimeInstruction-level tests, compute checks
SurfpoolA local network built as a drop-in replacement for solana-test-validator, that can pull mainnet accounts just in time or run --offlineEnd-to-end runs with RPC
solana-test-validatorThe local validator that ships with the Solana CLIProjects already set up around it

Sources: LiteSVM, Mollusk, Surfpool, Solana test validator.

How do I set up local testing for any coding agent?

  1. Install the toolchain and a local validator, such as Surfpool; check with surfpool --version.
  2. Tell the agent which command proves the work. For a fast loop, cargo test with LiteSVM or Mollusk tests. For an end-to-end run, anchor test, which builds, deploys to a local network, runs the tests and stops the network.
  3. Keep every command on a local cluster. Pass --url localhost (or -ul) to Solana CLI commands, and keep cluster = "localnet" in Anchor.toml while the agent works.
  4. Fund test accounts with local airdrops, not a real wallet. The agent never needs a funded mainnet keypair to test.
  5. Ask the agent to paste the real test output, and read logs with solana logs --url localhost when a program misbehaves.
surfpool --version
cargo test     # in-process tests, no validator
anchor test    # build, deploy to a local network, run the tests

How does Oh My Sol run a local chain for the agent?

Oh My Sol (OMS) starts its own Surfpool chain, pinned to version 1.7.0, offline, with no mainnet fork and no network. It binds to 127.0.0.1 on a free port pair between 20000 and 40000, so it does not collide with a validator you already run. npx @barestate/oms doctor --install downloads that exact Surfpool version and verifies its SHA-256.

You can look at and adjust the chain yourself without a model turn. The read-only commands also work while the agent is running.

CommandWhat it does
/chainRPC, slot, fork state and health
/airdrop <address> [sol]Sends SOL to an address, up to 100 SOL
/account [address]Shows a local chain account
/tx <signature>Status, error, compute units and logs
/testRuns the project tests in the sandbox
/rewind [confirm]Restarts the chain from its starting state

When the model proposes that a task is done, a separate checker starts a fresh offline Surfpool from a pinned snapshot and runs the task’s checks there, against a saved copy of the code. The task closes only when those checks pass, so state left over from the agent’s experiments cannot make a check pass.

What does a session look like?

npx @barestate/oms doctor --install
npx @barestate/oms
/chain                      # confirm the chain is healthy
/airdrop <address> 10       # fund a test wallet on the local chain
/test                       # run the project tests in the sandbox
/account <address>          # inspect what the program wrote
/rewind
/rewind confirm             # start again from a clean chain

If /chain reports a failed health check and OMS detects a crash, it restarts Surfpool from the latest checkpoint. Otherwise run npx @barestate/oms doctor and check the Surfpool line.

What can the agent reach on the local chain?

  • Every OMS session runs offline, with no mainnet fork, so a test reads only the accounts it set up. For real mainnet accounts, run Surfpool directly.
  • The chain commands use a small set of RPC methods: getHealth, getSlot, getVersion, getEpochInfo, getBalance, getAccountInfo, getTransaction and requestAirdrop.
  • /rewind discards everything created on the chain since its starting state.
  • OMS runs on macOS and Linux, or Windows under WSL 2, with Node 22.19.0 or newer and Git.

Frequently asked questions

What is the best way to test a Solana program locally?

For most Anchor projects, start with in-process tests (LiteSVM, or Mollusk for Rust), because they are fast and need no validator. Use a local network (Surfpool or solana-test-validator) when you need real RPC, deployment, or several programs and clients working together.

What is the difference between Surfpool and solana-test-validator?

Both run a local Solana network. Surfpool is built as a drop-in replacement for solana-test-validator that can fetch mainnet accounts just in time, or run with --offline and no remote data source. solana-test-validator ships with the Solana CLI. Check anchor test --help for how your Anchor version picks between them.

Can an AI coding agent run anchor test by itself?

Yes, if it can run shell commands in your project. Give it the exact command, make sure it targets a local cluster rather than devnet or mainnet, and have it report the actual output. Do not give it a funded mainnet keypair: on a local chain, airdrops are free.

Does Oh My Sol fork mainnet?

No. Oh My Sol (OMS) runs Surfpool 1.7.0 offline, with no mainnet fork and no network, so every run starts from the same known state. If you want real mainnet accounts in a test, run Surfpool yourself alongside OMS.

How do I reset the local chain in Oh My Sol?

Run /rewind, then /rewind confirm. It restarts the chain from its starting state, or from the original snapshot, and anything you created on the chain since then is gone.

Try it on your own program

Oh My Sol 0.1.0 runs on macOS and Linux, and on Windows through WSL 2. You need Node 22.19.0 or newer and Git. You bring your own model access: an API key, a ChatGPT subscription or a Claude subscription.

npx @barestate/oms doctor --install
npx @barestate/oms