Quickstart

Prerequisites

• Rust 1.96+ — pinned in rust-toolchain.toml, so rustup selects the right toolchain automatically.
• Node 22+ and pnpm 10+ — only needed for the TypeScript SDK (@rustag/sdk) and the Next.js dashboard. The CLI and runtime do not require them.
• A mainnet RPC endpoint — the source the lazy mirror fetches real state from. The public Solana endpoint works but is heavily rate-limited; a free Helius or Triton key is strongly recommended.

rustc --version    # 1.96.0+node --version     # v22+pnpm --version     # 10+

Build the CLI

From the repository root, build the release binary:

git clone https://github.com/ShahiTechnovation/RustAG && cd RustAGcargo build --release            # produces target/release/rustag

On Windows the binary is target/release/rustag.exe. Put target/release on your PATH so you can call rustag directly:

# macOS/Linuxexport PATH="$PWD/target/release:$PATH"# Windows PowerShell$env:PATH = "$PWD\target\release;$env:PATH" rustag --version        # rustag 0.1.0rustag --help           # lists all commands

Configure the mirror

Every stagenet reads its mirror endpoint from the RUSTAG_MAINNET_RPC environment variable (bound on the create command via clap's env attribute). Set it before creating stagenets:

cp .env.example .env.local      # then edit .env.local # macOS/Linuxexport RUSTAG_MAINNET_RPC="https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"# Windows PowerShell$env:RUSTAG_MAINNET_RPC = "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"

In RustAG.toml the same value is referenced as mirror.mainnet_rpc = "${RUSTAG_MAINNET_RPC}", so a committed project config and the environment stay in sync. If you skip it, RustAG falls back to a built-in default mainnet RPC — fine for a quick look, but rate-limited.

Your first stagenet

rustag start is a long-running foreground process — run it in its own terminal. --preload loads real mainnet programs/oracles on startup. A stagenet's data lives in ./.rustag/db.sqlite (project-local), so run these from your project directory.

rustag create demorustag start demo --preload pyth raydium

On startup it prints the three endpoints:

  ✓ Opened stagenet 'demo' (id: a1b2c3d4)  ✓ Preloaded 4 accounts from mainnet  ✓ RPC endpoint: http://127.0.0.1:8899  ✓ WebSocket:    ws://127.0.0.1:8900  ✓ REST API:     http://127.0.0.1:9000

Airdrop & inspect

The client commands (airdrop, override, preload, logs, status) talk to the running stagenet's REST API, so run them from a second terminal while start runs. Airdrops are unlimited — no faucet caps.

rustag airdrop -s demo <YOUR_WALLET> 1000     # 1000 SOL, no faucet limitrustag status  -s demo                        # counts, ports, running staterustag logs    -s demo --follow               # live transaction feed

You can read a real mainnet oracle straight through the stagenet's Solana RPC — the lazy mirror fetches and caches it on first read:

curl -s http://127.0.0.1:8899 -H 'content-type: application/json' \  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["7UVimffxr9ow1uXYxsr4LHAcV58mLzhmwaeKvJ1pjLiE",{"encoding":"base64"}]}'

Connect your tooling

The JSON-RPC endpoint at http://127.0.0.1:8899 is a drop-in cluster URL. Change one line in your test setup:

ANCHOR_PROVIDER_URL=http://127.0.0.1:8899 anchor testsolana config set --url http://127.0.0.1:8899solana balance <YOUR_WALLET> --url http://127.0.0.1:8899

From @solana/web3.js, construct a Connection against the RPC URL; connection.requestAirdrop works like a validator faucet, but unlimited:

import { Connection } from "@solana/web3.js"; const connection = new Connection("http://127.0.0.1:8899");await connection.requestAirdrop(pubkey, 2_000_000_000); // 2 SOL

SDK & dashboard

The TypeScript SDK and the Next.js dashboard only need the Node toolchain:

pnpm installNEXT_PUBLIC_RUSTAG_API_URL=http://localhost:9000 pnpm --filter dashboard dev# open http://localhost:3000

Early-access limits