Skip to main content

Walrus Sites Components

A Walrus Site is made up of 4 main components that work together: the site's files stored on Walrus, a Sui object that indexes those files as resources, the site-builder CLI that publishes and updates the site, and a portal that serves the site to browsers.

Site files on Walrus​

Your site's static assets (HTML, CSS, JavaScript, images, fonts, and so on) are stored as blobs on Walrus. When you deploy a site, the site-builder uploads your assets to Walrus by encoding multiple files into a single storage entity called a quilt, a unique feature designed to reduce upload cost and improve upload speed. Each file in the quilt is assigned a QuiltPatchID.

The Sui site object​

Each Walrus Site corresponds to a single object on Sui, defined by the Move smart contract in the move/walrus_site directory of the repository. Unlike storing a single blob directly on Walrus, a Walrus Site bundles all its files into a quilt and represents the entire site as one Sui object. At its core, a site object is a simple structure:

struct Site has key, store {
    id: UID,
    name: String,
}

Each resource in the site is attached to this object as a dynamic field of type Resource:

struct Resource has store, drop {
    path: String,
    blob_id: u256,
    // ...headers and other metadata
}

The path field corresponds to the resource's URL path (for example, /index.html), and blob_id is the Walrus identifier for the resource's content. The site object uses each file's QuiltPatchID to locate and retrieve it from the quilt. Together, the site object and its dynamic fields form an onchain index that maps every resource path in your site to its content on Walrus. Because Walrus is a decentralized storage network, there is no single server that can take your content offline.

Because the site object is a standard Sui object, it has a single owner. The wallet that deployed the site owns the object and is the only wallet that can update or destroy it. Ownership can also be transferred, meaning you can move a site to a different wallet if needed. For more detail on how Sui handles object ownership, see the Sui object model documentation. You can also assign a SuiNS name to the object, giving your site a human-readable domain name.

info

Blobs are stored for a fixed number of epochs. On Mainnet, each epoch lasts 14 days. On Testnet, each epoch lasts 1 day. The maximum storage duration is 53 epochs.

The site-builder CLI​

The site-builder is a Rust CLI tool that creates and manages Walrus Sites. It takes your site's build output directory as input and handles uploading files to Walrus and writing the onchain index to Sui.

The primary command is deploy, which both publishes new sites and updates existing ones:

site-builder deploy --epochs <NUMBER> <DIRECTORY>

The site-builder requires a sites-config.yaml configuration file that specifies the Sui package ID for the Walrus Sites contract and your network context.

When you run deploy for the first time, it publishes a new site and writes the resulting Sui object ID to the object_id field in ws-resources.json. On subsequent runs, deploy reads that object ID and updates the existing site instead of creating a new one.

ws-resources.json​

ws-resources.json is a configuration file the site-builder reads during deployment to control how your site is built and served. The file itself is not uploaded to Walrus and is not accessible to visitors.

The file supports the following fields (see the configuration reference for more details):

{
  // Written automatically after the first deploy; subsequent deploys update this site
  "object_id": "0x...",
 
  // Custom HTTP response headers per resource (cache control, content type, etc.)
  "headers": {},
 
  // Client-side routing rules for SPA frameworks like React or Angular
  "routes": {
    "/app/*": "/index.html"
  },
 
  // Site metadata stored in the Sui object and displayed in wallets
  "metadata": {
    "site_name": "My Site",
    "description": "A site built on Walrus.",
    "link": "https://example.wal.app"
  },
 
  // Path patterns to exclude from deployment
  "ignore": []
}
caution

Walrus Sites does not support dynamic redirects. Redirect plugins used in frameworks like Docusaurus resolve routes at the server level, which Walrus Sites does not have. Use the routes field in ws-resources.json to simulate client-side routing instead.

Portals​

A portal resolves and serves a Walrus Site to a visitor's browser. When a visitor navigates to a Walrus Site URL, the portal performs the following steps:

  1. Resolves the subdomain to a Sui object ID, either through a SuiNS name lookup or by decoding the Base36-encoded object ID directly from the subdomain.
  2. Reads the site object's dynamic fields from Sui to get the resource map.
  3. Fetches the resource from Walrus using the blob_id from that map.
  4. Returns the resource to the browser with the appropriate headers.

This process repeats for every resource the browser requests, such as linked CSS files, scripts, and images.

The public Mainnet portal operated by Mysten Labs is available at https://wal.app. Sites with a SuiNS name are accessible directly by name. For sites without one, use the Base36-encoded object ID as the subdomain, or run site-builder convert to find it.

Anyone can host their own portal. For setup instructions, see Deploy a Local Portal.