---
title: "The local chain"
description: "How OMS runs Surfpool 1.7.0 offline on your machine, and how checkpoints and rewind work. Read it when the chain misbehaves or you want to know what it can reach."
url: https://barestate.xyz/docs/concepts/local-chain
---

# The local chain

> How OMS runs Surfpool 1.7.0 offline on your machine, and how checkpoints and rewind work. Read it when the chain misbehaves or you want to know what it can reach.

OMS runs a local Solana chain with Surfpool. The chain is offline, with no mainnet fork and no network, so a run can't depend on outside state. The version is pinned to 1.7.0, and `oms doctor` requires an exact match.

## How OMS starts it

OMS starts Surfpool with `--ci --no-tui --offline`, an RPC port and a websocket port, and an airdrop amount of 0. When a snapshot is given, it adds `--snapshot <file>`. The process gets only a small environment: `PATH`, `HOME`, `LANG`, `LC_ALL`, `TMPDIR`, `SHELL`, `TERM` and `NO_DNA=1`.

For ports, OMS picks a free pair on `127.0.0.1` in the range 20000 to 40000: an even RPC port and the next odd port.

## Checkpoints and rewind

![Surfpool 1.7.0 runs offline on 127.0.0.1 with no network and no mainnet fork. It uses an even RPC port and the next odd websocket port, picked from 20000 to 40000. A checkpoint exports a snapshot and records its SHA-256. A rewind stops the process and starts a new one from the checkpoint on the same ports. The snapshot hash is checked before every start.](https://barestate.xyz/docs/images/diagrams/local-chain-light.svg)

*Surfpool runs offline on 127.0.0.1. A rewind starts a new process from a checkpoint on the same ports, after checking the snapshot hash.*

| Action | What happens |
|---|---|
| Checkpoint | Exports a snapshot to `<workDir>/checkpoints/<name>.json` and records its SHA-256. Names match `^[A-Za-z0-9._-]+$` |
| Rewind | Stops the process and starts a new one from that checkpoint on the same ports |
| Rewind to start | Restarts from the original startup snapshot, or empty |
| Crash recovery | Restarts from the latest checkpoint, or the original snapshot |

OMS hashes the snapshot bytes again before every start. If the file changed, it refuses with "surfnet snapshot bytes changed since verification". State-changing RPC calls run in order, while reads run at once.

## Offline and forked modes

Every shipped session runs offline. A `forked` run can never close a task, and forked mode isn't reachable from the terminal app.

## What you can ask the chain

The chain commands (`/chain`, `/airdrop`, `/tx`, `/account` and `/rewind`) run against the local Surfpool with no model involved. They allow only these RPC methods: `getHealth`, `getSlot`, `getVersion`, `getEpochInfo`, `getBalance`, `getAccountInfo`, `getTransaction` and `requestAirdrop`. Cheat codes are not reachable.

See [Use the local chain](https://barestate.xyz/docs/guides/use-the-local-chain) for the commands.

## If Surfpool will not start

Run `npx @barestate/oms doctor`. It checks that the Surfpool binary runs and reports exactly 1.7.0. If it doesn't, run `npx @barestate/oms doctor --install` again.