Docs - Sandbox Management - BuildBear Labs

Manage BuildBear sandboxes — create forks of live networks, list existing sandboxes, delete them, and browse supported networks.

sandbox create

Create a new sandbox that forks a supported network.

buildbear sandbox create [options]

Options:

Flag	Type	Default	Description
`--network <chainId>`	string	—	Chain ID of the network to fork (e.g. `1` for Ethereum, `10` for Optimism). Run `buildbear sandbox networks` to see all chain IDs
`--fork-block <blockNumber>`	string	latest	Block number to fork from
`--chain-id <customChainId>`	string	—	Override the chain ID inside the sandbox
`--prefund <addresses>`	string	—	Comma-separated wallet addresses to pre-fund
`--name <label>`	string	—	Human-readable name for the sandbox
`--json`	flag	—	Output as JSON
`--quiet`	flag	—	Suppress output except errors

Example — fork Ethereum mainnet:

buildbear sandbox create --network 1 --name "my-test-fork"

Example — fork at a specific block and pre-fund an address:

buildbear sandbox create \
  --network 1 \
  --fork-block 21000000 \
  --prefund 0xYourWalletAddress \
  --name "block-21m-fork"

Example — JSON output for scripting:

buildbear sandbox create --network 137 --json

{
  "status": "live",
  "sandboxId": "abc123",
  "forkingDetails": { "chainId": 137, "blockNumber": 60000000 },
  "chainId": 31337,
  "rpcUrl": "https://rpc.buildbear.io/abc123",
  "explorerUrl": "https://explorer.buildbear.io/abc123",
  "faucetUrl": "https://faucet.buildbear.io/abc123",
  "mnemonic": "word1 word2 word3 ... word12"
}

[!NOTE] The mnemonic in the JSON output is a fresh test mnemonic for the sandbox — it is not a real wallet. Do not send real funds to addresses derived from it.

sandbox list

List all your sandboxes.

buildbear sandbox list [options]

Options:

Flag	Type	Description
`--status <status>`	string	Filter by status: `live`, `dead`, or `pending`
`--limit <n>`	number	Maximum number of results to show
`--filter <pattern>`	string	Case-insensitive substring match against sandbox name or ID
`--json`	flag	Output as JSON
`--quiet`	flag	Suppress output except errors

Example:

buildbear sandbox list

Sandbox ID      Name             Status    RPC URL
──────────────  ───────────────  ────────  ────────────────────────────────────────
abc123          my-test-fork     live      https://rpc.buildbear.io/abc123
def456          block-21m-fork   live      https://rpc.buildbear.io/def456

sandbox delete

Permanently destroy a sandbox by its RPC URL.

buildbear sandbox delete <rpcUrl> [options]

Arguments:

Argument	Required	Description
`rpcUrl`	Yes	Full BuildBear RPC URL (e.g. `https://rpc.buildbear.io/abc123`)

Options:

Flag	Description
`--json`	Output as JSON
`--quiet`	Suppress output except errors

Example:

buildbear sandbox delete https://rpc.buildbear.io/abc123

[!WARNING] Deletion is permanent. All sandbox state, snapshots, and funded balances will be lost.

sandbox networks

List all networks that can be forked.

buildbear sandbox networks [options]

Options:

Flag	Description
`--json`	Output as JSON
`--quiet`	Suppress output except errors

Example output:

Network     Label       Chain ID
──────────  ──────────  ────────
Ethereum    mainnet     1
Optimism    mainnet     10
Polygon     mainnet     137
Arbitrum    mainnet     42161
Base        mainnet     8453
...

Use the Chain ID column value with --network when creating a sandbox.

Sandbox Management

sandbox create

sandbox list

sandbox delete

sandbox networks

On this page