# Surfpool replaces solana-test-validator and adds Infrastructure as Code

> Surfpool is a Rust implementation of a local Solana network that mirrors mainnet state without downloading the whole chain, and it adds declarative infrastructure definition, IDL to SQL indexing, cheatcodes and curated chain scenarios on top. The trade is that it reimplements the validator rather than wrapping it, and the ecosystem tools it supports are a listed set rather than all of them.

**solana-foundation/surfpool** — Surfpool is where developers start their Solana journey.

- Repository: https://github.com/solana-foundation/surfpool
- Website: https://surfpool.run
- Stars: 615 · Forks: 195
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/solana-foundation-surfpool

## A local validator without the snapshot

Surfpool is described as a drop-in replacement for solana-test-validator, designed for builders who want to work with real mainnet state without downloading the entire chain.

That last clause is the whole point. The conventional local Solana setup involves fetching a snapshot of mainnet state, and the documentation puts a number on it: no 2 TB snapshots. The project says it can spin up local networks that mirror mainnet state instantly, and that it runs on a Raspberry Pi.

Being a drop-in replacement is a strong claim, and the documentation supports it in a specific way. Surfpool has been used with existing Solana tools including solana-cli, anchor and Kit, so the claim is that you plug it into your workflow without changing anything. The word including matters, because it names a set rather than asserting universal compatibility, and a set is what you should test against before you migrate a pipeline.

The project is Rust, licensed Apache-2.0, and its Cargo workspace is version 1.6.1 on edition 2024. The last push was on 2026-10-20, with v1.6.1 released on 2026-10-10, v1.6.0 on 2026-09-18 and v1.5.0 on 2026-07-13, so this is a project shipping steadily rather than one waiting for a rewrite.

## LiteSVM is the reason it boots fast

The architecture note is short and it explains the design. Surfpool is built on the low-level solana-svm API, using the LiteSVM wrapper, and the approach is said to provide greater flexibility and significantly faster boot times.

The distinction is between a full validator and an execution layer. A validator does consensus, gossip and block production, and a test validator does a simplified version of that. LiteSVM is the part that executes transactions against a ledger state, without the network layer. Building on it means Surfpool is doing what a test validator does, without the parts of a validator that a local test does not need, and the boot time is a consequence of that choice rather than a separate optimisation.

That choice also explains the mainnet state part. A validator that has never seen mainnet has an empty ledger, so the only way to mirror mainnet is to fetch the accounts you need from somewhere. Surfpool's approach of not requiring a full snapshot implies a per account or per request fetch rather than a bulk state load, which is why the IDL to SQL engine, described as automatically generating tables and syncing chain data to local SQLite or Postgres for instant indexing and analytics, sits so naturally in the design.

The repository layout follows the same separation. The Cargo workspace has members for bench, cli, core, db, mcp, sdk, sdk-node, studio and types, with the CLI as the default member, so the binary, the server core, the database layer, the MCP server, the studio dashboard and the SDK are separate crates.

## Infrastructure as Code is the differentiator, not the validator

The second claim in the project description is that Surfpool goes further and introduces Infrastructure as Code for Solana, empowering developers to define, deploy and operate both on-chain and off-chain infrastructure declaratively and reproducibly.

The framing is explicitly inspired by Terraform, and the documentation spells out the intent in three properties. Declarative and reproducible, because environments are clearly defined, making deployments consistent. Auditable, because security teams can review not just the code of your Solana programs but the way you will be deploying and operating your protocol. And a direct transition to mainnet, because you test with the exact infrastructure that will go live.

The mechanism is visible in the Anchor integration. If you are inside an Anchor project, Surfpool will automatically generate infrastructure as code, deploy your Solana programs to the local network, and provide a clean, structured environment to iterate safely. In other words, the IaC layer is not a separate configuration language you opt into; it is what the tool produces for you in the case it recognises.

The conceptual move is worth naming, because it is the difference between a test harness and a deployment tool. A test harness answers the question of whether your program works. An IaC layer answers the question of what your environment is, in a form that can be reviewed, diffed and applied again. Surfpool is trying to be the second thing while remaining a drop-in for the first, and the local-first and offline-ready design is what makes that promotion plausible, since the same setup can be moved to the cloud when it is time.

## Cheatcodes and scenarios are where the testing power is

Two features let you simulate conditions you cannot easily produce.

The cheatcodes are described as letting you simulate, debug and replay transactions without touching mainnet, and four are named. Stream Oracles push price feeds into your local network so a program that depends on an oracle can be tested against controlled values. The Universal Faucet funds accounts. The Transaction Inspector lets you look at what a transaction did. And Time Travel moves the chain state to a chosen point.

The scenarios feature is the more interesting one. With Surfpool Scenarios you can curate slot-by-slot account states for key accounts, mixing live mainnet data with overridden account states. The stated purpose is to stress test your protocol in key real-world situations and to reproduce any chain-state conditions. That is a different capability from a seeded random ledger: a scenario is a fixture, a description of a chain state you want to be able to reproduce, and the documentation points to a scenarios README inside the core crate for the details.

Taken together, cheatcodes and scenarios are what make the tool more than a faster validator. A local validator with a fixture generator gives you deterministic tests. A local validator with a real mainnet account state that you can override at the slot level gives you the ability to test against the state your users will actually be in, which is the situation most protocol bugs live in.

## Installing it three ways, and the Docker port detail that bites

The installer is a single shell pipeline:

```console
curl -sL https://run.surfpool.run/ | bash
```

Building from source clones the repository and runs a Cargo subcommand:

```console
# Clone repo
git clone https://github.com/solana-foundation/surfpool.git

# Set repo as current directory
cd surfpool

# Build
cargo surfpool-install
```

And there is a public Docker image, which can be checked with a version flag:

```console
docker run surfpool/surfpool --version
```

The interesting Docker detail is the port binding. The image binds to 0.0.0.0 inside the container but advertises 127.0.0.1 by default, so local Docker workflows get usable URLs with no extra configuration. The three ports exposed are 8899 for RPC, 8900 for WebSocket and 18488 for the studio. When the container needs to be reachable from another machine, you override SURFPOOL_PUBLIC_HOST:

```console
docker run --rm \
  -p 8899:8899 -p 8900:8900 -p 18488:18488 \
  -e SURFPOOL_PUBLIC_HOST=staging.example.com \
  surfpool/surfpool
```

And for fully custom externally visible URLs, such as TLS termination or remapped ports, you override SURFPOOL_PUBLIC_RPC_URL, SURFPOOL_PUBLIC_WS_URL and SURFPOOL_PUBLIC_STUDIO_URL. The Dockerfile sets the same defaults as environment variables, SURFPOOL_NETWORK_HOST=0.0.0.0 and SURFPOOL_PUBLIC_HOST=127.0.0.1, and includes a health check that posts a getHealth JSON RPC call to the RPC port.

## Studio, Cloud and an MCP server for agents

There are two surfaces for the same environment. Surfpool Studio is the local dashboard for visualising, inspecting and managing your networks in real time. Surfpool Cloud extends that same experience to the cloud, letting you index mainnet data and run large-scale simulations with the same developer experience, described as serverless, backend-as-a-service and built for analytics at scale.

That last part is a business product rather than an open source one, and it is worth separating from the local tool when you decide what to adopt.

The third surface is for automation. Surfpool is described as getting agentic friendly, thanks to a built-in MCP. The first use case named is starting a local network with a given set of users loaded with specific tokens, and the documentation gives the exact configuration to paste into a client, in this case Cursor, by adding a global MCP server through the command palette:

```json
{
  "mcpServers": {
    "surfpool": {
      "command": "surfpool",
      "args": ["mcp"]
    }
  }
}
```

There is also an .mcp.json file in the repository root, so the server can be registered from a project rather than globally. The workspace includes a dedicated crates/mcp member, so the MCP server is a first-class part of the build rather than a wrapper script.

## Where Surfpool is the wrong tool

Four situations argue against it.

The first is a test that only needs an empty ledger. If your test creates accounts, deploys a program and asserts on a result, solana-test-validator already does that and is the tool Solana ships for it. Surfpool's features are about mirroring mainnet state and about infrastructure definition, and neither of those is what an empty ledger test needs. The added surface is a reimplementation of the validator with extra subsystems, and there is no reason to take that on for a unit test.

The second is a project with a wide client ecosystem. The compatibility claim names solana-cli, anchor and Kit. If your team also uses a wallet SDK, a third party indexer, a TypeScript client, or a tool that talks to the validator over an undocumented interface, you have to test each one, because a reimplementation of the validator is only guaranteed to behave like the real thing on the paths it has been tested on.

The third is an offline or air gapped environment with specific state needs. Surfpool is local-first and offline-ready, which is a good property, but mirroring mainnet state is inherently a fetch operation at some point, and how much state it can obtain without a full snapshot, and what it does when the requested account is not fetchable, is not described in the available documentation. That is a question to answer before designing a test strategy around it.

The fourth is reproducibility across environments. The IaC story is compelling but it is new, and the documentation does not describe a file format for the environment definitions, a diff format, or a state file you can commit. A Terraform-like tool without a committed state file is a script, and until you can see what the generated infrastructure actually is, auditing it is harder than the documentation implies.

The alternative worth naming is solana-test-validator with a fixtures layer of your own, which is what most teams do. The difference in approach is that Surfpool reuses the same definitions for local and cloud, while a fixtures approach keeps your chain fixtures in the test code and gives up on the promotion story. If you never intend to run the same environment in the cloud, the IaC benefit does not apply and the simpler tool wins.

## Conclusion

Surfpool fits a Solana team that has outgrown solana-test-validator, either because mainnet state matters to the test or because the same local environment needs to be promoted to a hosted environment later. It is the wrong choice if your tests only need an empty ledger with a few accounts, since a plain local validator does that with less machinery, and it is the wrong choice if you need every Solana client to work, since the compatibility claim covers a named set of tools rather than the whole ecosystem. Before adopting it, check three things: that the state your test needs is actually reachable, since mirroring mainnet without downloading the chain depends on what Surfpool can fetch rather than on a local snapshot, that the client libraries you use are among the supported ones, and that the cheatcode and scenario features you plan to rely on are documented for the version you pin, since the project is pre-1.0 in its interface conventions even at v1.6.1.

## FAQ

### What is Surfpool and how does it differ from solana-test-validator?

Surfpool is a drop-in replacement for solana-test-validator, built for working with real mainnet state without downloading the entire chain, and the documentation says no 2 TB snapshots are needed. It is built on the low-level solana-svm API using the LiteSVM wrapper, which is what provides the faster boot times.

### How do I install Surfpool?

The installer runs curl -sL https://run.surfpool.run/ | bash, or you can clone the repository and run cargo surfpool-install, or use the public Docker image with docker run surfpool/surfpool. Verify the install with surfpool --version.

### What are Surfpool cheatcodes and what do they include?

Cheatcodes let you simulate, debug and replay transactions without touching mainnet. The four named are Stream Oracles, Universal Faucet, Transaction Inspector and Time Travel, the last of which moves the chain state to a chosen point.

### What are Surfpool Scenarios?

Scenarios let you curate slot-by-slot account states for key accounts, mixing live mainnet data with overridden account states. The purpose is to stress test a protocol in real-world situations and to reproduce specific chain-state conditions, with details in a scenarios README in the core crate.

### How do I run Surfpool in Docker with the right ports?

The image binds to 0.0.0.0 inside the container but advertises 127.0.0.1 by default, so use docker run --rm -p 8899:8899 -p 8900:8900 -p 18488:18488 surfpool/surfpool for local work. To make it reachable from another machine, set SURFPOOL_PUBLIC_HOST, or override SURFPOOL_PUBLIC_RPC_URL, SURFPOOL_PUBLIC_WS_URL and SURFPOOL_PUBLIC_STUDIO_URL for custom URLs.

## Sources

- [License: Apache-2.0](https://github.com/solana-foundation/surfpool/blob/main/LICENSE)
- [Project website](https://surfpool.run)
- [README](https://github.com/solana-foundation/surfpool/blob/main/README.md)
- [Releases](https://github.com/solana-foundation/surfpool/releases)
- [solana-foundation/surfpool on GitHub](https://github.com/solana-foundation/surfpool)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/solana-foundation-surfpool