suibase.io

Walrus is fully integrated with Suibase, so it "just works" out of the box.

Suibase makes it easy to develop concurrently with Walrus localnet, testnet and mainnet with the peace of mind that every operation is done with the proper binary and config matching the network.

The localnet is especially valuable: being fast and deterministic, it is ideal for GitHub Actions and AI coding agent workflows — no wallets to fund, no public network to wait on. Blob reads are served straight from local disk in milliseconds.

Walrus CLI

Use twalrus for testnet and mwalrus for mainnet, instead of calling walrus directly.

For Walrus Sites, use tsite and msite instead of site-builder.

Suibase scripts append the proper --config, --context and wallet path to make sure you are using the correct mix of binaries and configs.

The scripts pass all your command line parameters as-is to the original Mysten Labs binaries.

The exception is localnet: lwalrus uses a custom binary to short-circuit to local storage, and supports only a functional subset. See Localnet.

Updates

Run testnet update or mainnet update.

This updates all binaries/configs to match the latest deployed testnet/mainnet.

For localnet, localnet update refreshes its tools, and localnet regen re-deploys Walrus on a fresh chain.

Run ~/suibase/update periodically to keep Suibase itself up-to-date.

Wallets

Some walrus commands require a wallet. By default, the active-address of the Suibase wallet is used.

This wallet has 15 addresses automatically generated when you installed Suibase.

Use tsui and msui, instead of sui, to access the proper wallets. Some useful commands are:

$ tsui client active-address
$ tsui client gas
$ tsui client switch --address <address or alias>
# Note: For mainnet, use `msui` instead.

Getting WAL (SUI → WAL)

Walrus storage is paid in WAL. How you obtain it depends on the network:

Testnet — convert SUI to WAL for free with twalrus get-wal (uses the testnet WAL exchange; defaults to 0.5 SUI, override with --amount <MIST>). Fund the wallet with SUI first via tsui client faucet.
Mainnet — WAL is a real token with no faucet or exchange command; acquire it on an exchange/DEX, then mwalrus spends it automatically.
Localnet — nothing to do: the localnet Walrus mints WAL on demand (the deploy sets up a SUI→WAL exchange, and the publisher / walrus_local_sdk fund the wallet automatically on first use).

File Locations

Backup your wallets.

All wallets (sui.keystore) and yaml configs are stored in:

localnet: ~/suibase/workdirs/localnet/config/
testnet: ~/suibase/workdirs/testnet/config/
mainnet: ~/suibase/workdirs/mainnet/config/

A convenient recovery.txt file (in the same config/ directory) has the mnemonics of the 15 addresses generated by Suibase.

Walrus Relay

For advanced HTTP proxy functionality with request statistics and transparent forwarding, see Walrus Relay.

Localnet

Suibase also runs Walrus on localnet — a self-contained Walrus (no storage nodes, no internet). Enable it in ~/suibase/workdirs/localnet/suibase.yaml:

walrus_local_enabled: true

then run localnet regen to deploy it. This gives you:

Automatic deployment — the genuine Mysten Labs Walrus Move contracts (the same ones deployed on testnet) are published on localnet for you.
An aggregator + publisher HTTP API — the same /v1/blobs wire API as the real walrus daemon, at http://localhost:45840. Point any Walrus HTTP client at it by changing only the URL.
walrus_local_sdk — a Rust crate that mirrors Mysten's walrus_sdk (same method signatures, same return types).
@suibase/walrus-local — a TypeScript drop-in for Mysten's @mysten/walrus that works against the localnet Walrus. Same class, same methods, same signatures.
lwalrus — a localnet, walrus-style command-line tool for quick blob operations from the shell (a focused subset of the real walrus CLI; see lwalrus --help).

Check it is running with localnet status, then use it like any Walrus aggregator/publisher:

# Publish a file (the response contains the blobId)
$ curl -X PUT --data-binary @myfile http://localhost:45840/v1/blobs
# Read it back
$ curl http://localhost:45840/v1/blobs/<blobId> -o out
# Inspect the real on-chain Blob object (its id is newlyCreated.blobObject.id)
$ lsui client object <objectId>

Or use the lwalrus CLI for the same round-trip:

$ lwalrus store ./myfile            # prints the blob id
$ lwalrus read <blobId> --out out
$ lwalrus blob-status <blobId>
$ lwalrus delete <blobId>           # deletable blobs only

From TypeScript, use the exact same @mysten/walrus API you'd use on testnet/mainnet (requires Node ≥ 22):

import { WalrusLocalClient } from "@suibase/walrus-local";

// On localnet: use WalrusLocalClient as a drop-in WalrusClient replacement.
// On testnet: use new WalrusClient({ network: "testnet", suiClient }) instead.
// Same methods after that.
const client = new WalrusLocalClient();
const { blobId, blobObject } = await client.writeBlob({ blob, deletable: true, epochs: 5, signer });
const bytes = await client.readBlob({ blobId });                       // node-talking
await client.executeDeleteBlobTransaction({ blobObjectId: blobObject.id, signer }); // inherited, on-chain

Parity with testnet is the goal: on-chain Blob objects, quilts, the SDK surface, and the HTTP error contract all match — so what works on localnet behaves the same on testnet/mainnet.