Skip to main content
skill CX Codex

walrus-sites — Claude Code skill: what it does, how to install

walrus-sites — a Claude Code skill for deploying, updating, and serving decentralized websites on Walrus and Sui. Helps set up a local portal for testnet and configure routing in ws-resources.json.

Apache-2.0 467 installs ★ 25 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MystenLabs/skills --skill walrus-sites -a claude-code
Open on GitHub

What walrus-sites does

Deploys static web frontends to Walrus storage and maps site resources to on-chain Sui site::Site objects. It guides usage of the site-builder CLI for publishing builds with the --epochs flag, updating existing sites, inspecting files via site-builder sitemap, and tearing down objects with site-builder destroy.

It guides setting up a local portal with Bun for testnet development. The public wal.app gateway resolves mainnet only, so testnet deployments require a local portal resolver. In portal-config.yaml, original_package_id must point directly to the Walrus Sites framework package rather than an application Move package.

For single-page applications, it explains how to configure fallback routes inside ws-resources.json to prevent client-side 404 errors. Publishing requires building static files first, and setting --epochs to at least 30 prevents storage blobs from expiring prematurely. It can also query https://sui.mcp.kapa.ai when the Sui MCP server is present in the environment.

What it helps with

  • publish a static frontend to Walrus decentralized storage
  • configure client-side SPA routing fallbacks in ws-resources.json
  • run a local testnet portal using Bun
  • check blob expiration dates with site-builder sitemap

Example prompts for the agent

  • Deploy the static dist directory to Walrus Sites with --epochs 30
  • Configure client-side routing fallback rules in ws-resources.json
  • Set up a local testnet portal for Walrus Sites using Bun

How to install walrus-sites

1Skills CLI (Vercel)

npx skills add MystenLabs/skills --skill walrus-sites -a claude-code

2Manually: put the files in place

~/.claude/skills/walrus-sites/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/walrus-sites/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about walrus-sites

How to install walrus-sites in Claude Code?

Run npx skills add MystenLabs/skills --skill walrus-sites -a claude-code.

What does the walrus-sites skill do?

It guides deploying frontends using site-builder, managing blob duration in epochs, setting up ws-resources.json, and running a local portal server.

Why does a Walrus testnet site return 404 on wal.app?

The public wal.app gateway serves mainnet sites only. Viewing testnet sites requires a local portal server hosted with Bun.

Source text

SKILL.md · Apache-2.0
---
name: walrus-sites
description: >
  Publishing, updating, and serving decentralized websites on Walrus Sites.
  Use when the user needs to deploy a frontend to Walrus Sites, run a local
  portal for testnet, debug site-builder errors, configure ws-resources.json,
  or manage site object lifecycle (update, destroy, extend blobs). Also use
  when the user asks about site-builder, walrus-sites, portal setup, or
  hosting a dApp on Walrus. For blob storage without the Sites framework
  (raw upload/download), see the `accessing-data` skill's walrus.md.
---

# Walrus Sites — Decentralized Website Hosting

> **MCP tool:** When available in your environment, also query the Sui documentation MCP server (`https://sui.mcp.kapa.ai`) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Walrus Sites lets you deploy a static website (HTML/CSS/JS) to Walrus, with an on-chain Sui object tracking the site's resources. A portal server resolves site subdomains, fetches resources from Walrus, and serves them over HTTP. The result is a fully decentralized frontend — no centralized server, CDN, or DNS required.

> **Source constraint:** All information in this skill is sourced from the [MystenLabs/walrus-sites](https://github.com/MystenLabs/walrus-sites) repository and the [Walrus Sites documentation](https://docs.wal.app/docs/sites). When extending or updating this skill, only pull from these sources. Do not use third-party blogs or unofficial tutorials.

Common failures:

1. **Blobs expire.** Sites published with too few epochs silently break — the portal returns 404 once the blobs expire. Always use a generous `--epochs` value (30+).
2. **Portal misconfiguration.** The portal's `original_package_id` must match the Walrus Sites framework package (`site::Site`), not your app's Move package. The testnet example config ships with the correct value — don't change it.
3. **Testnet sites can't use `wal.app`.** The public `wal.app` portal only serves mainnet sites. Testnet requires a self-hosted local portal.
4. **SPA routing.** Single-page apps need `ws-resources.json` routes config to handle client-side routing. Without it, direct navigation to `/my-route` returns 404.

---

## Sub-skills

### publishing — Building and deploying sites
**Path:** `publishing/SKILL.md`
**Load when:** deploying a new site, updating an existing site, choosing epoch duration, configuring `ws-resources.json`, or troubleshooting `site-builder` errors.
**Covers:** `site-builder publish`, `site-builder update`, `--epochs` flag, blob expiration, `ws-resources.json` configuration, SPA routing, site naming, `site-builder sitemap` for debugging, `site-builder destroy`.

### portal — Running a local portal for testnet
**Path:** `portal/SKILL.md`
**Load when:** the user needs to view a testnet site, set up the local portal, fix portal 404s, or understand how portal resolution works.
**Covers:** cloning the portal, installing dependencies (Bun), `portal-config.yaml`, the `original_package_id` gotcha, starting the server, URL format, port conflicts, mainnet vs testnet differences.

---

## Routing guide

| Task | Load |
|------|------|
| Deploy a frontend to Walrus Sites | `publishing/` |
| Update an existing deployed site | `publishing/` |
| Fix 404 or expired site | `publishing/` + `portal/` |
| View a testnet site locally | `portal/` |
| Set up the local portal | `portal/` |
| Portal shows "Page not found" | `portal/` + `publishing/` (check blob expiry) |
| Configure SPA routing | `publishing/` |
| Check what resources a site has | `publishing/` (`site-builder sitemap`) |
| Delete a deployed site | `publishing/` |
| Choose between Walrus Sites and traditional hosting | Skill Content below |

---

## Skill Content

### Key concepts

- **Site object.** A Sui object of type `site::Site` (from the Walrus Sites framework package). It holds metadata (name, description) and dynamic fields mapping resource paths to Walrus blob references. Created by `site-builder publish`, owned by the publisher's address.

- **Resources.** Each file in the deployed directory becomes a resource stored on Walrus. Small files may be batched into a single "quilt" blob. Each resource has a path (e.g., `/index.html`, `/assets/main.js`) and optional HTTP headers.

- **Portal.** A server that maps `<base36-site-id>.localhost:3000` URLs to on-chain site objects. It reads the site's dynamic fields to find the requested resource path, fetches the blob from a Walrus aggregator, and returns it as an HTTP response. The portal is framework-level infrastructure, not part of your app.

- **`ws-resources.json`.** A configuration file in the site's root directory that controls resource headers, routing, and site metadata. Auto-generated on first publish with the site object ID. On subsequent runs, the site-builder reads it to determine whether to create a new site or update the existing one.

- **Blob expiration.** Walrus blobs have a finite storage duration measured in epochs. When blobs expire, the portal can no longer fetch them and returns 404. Use `site-builder sitemap <object-id>` to check expiration dates. Re-publish with a higher `--epochs` value to fix.

### Rules

1. **Always use `--epochs 30` or higher for testnet deploys.** Low values (like 5) cause blobs to expire within days. For production mainnet, use even higher values or `--permanent`.
2. **Build before publishing.** Run `npm run build` (or equivalent) to produce a static `dist/` directory. The site-builder publishes whatever directory you point it at.
3. **Don't change `original_package_id` in the portal config** unless you know the Walrus Sites framework package has been upgraded. The testnet example value is correct.
4. **`wal.app` is mainnet only.** For testnet, self-host the portal from the `MystenLabs/walrus-sites` repo.
5. **Check `ws-resources.json` after first publish.** It records the site object ID. Keep it in version control so future publishes update the existing site rather than creating a new one.

### Common mistakes

- **Publishing with `--epochs 5` and wondering why the site is gone a week later.** Blobs expired. Re-publish with `--epochs 30+`.
- **Changing the portal's `original_package_id` to your app's package ID.** The portal needs the Walrus Sites framework package ID (`site::Site`), not your Move contract's package ID. These are completely different things.
- **Trying to visit a testnet site on `wal.app`.** It only serves mainnet. You need a local portal for testnet.
- **Forgetting to build the frontend before publishing.** `site-builder publish dist/` publishes the `dist/` directory contents. If you didn't `npm run build` first, you're publishing source files or stale output.
- **Deploying an SPA without fallback routing.** React/Vue/Svelte SPAs use client-side routing. Direct navigation to `/borrows` hits the portal, which looks for `/borrows` as a resource — and it doesn't exist. Configure a fallback in `ws-resources.json`.
- **Not killing port 3000 before starting the portal.** Vite dev server, Next.js, or other tools often use port 3000. The portal silently fails to bind if the port is taken.

© MystenLabs · Apache-2.0 · MystenLabs/skills

Similar skills

All skills for Frontend and UI →

From the same set30

The whole set →
accessing-data accessing-data — a skill for Claude Code that guides data fetching on Sui across gRPC, GraphQL RPC, Archival Store, Walrus, and sui-indexer-alt. Triggers on queries about balances, objects, and JSON-RPC migrations. CX Codex +1 491installs ptbs ptbs — a skill for Claude Code helps write, review, and debug Sui Programmable Transaction Blocks. It applies to TypeScript SDK and CLI transactions, gas handling, and sponsored flows. CX Codex +1 491installs sui-sdks sui-sdks — a Claude Code skill for navigating the Sui blockchain SDK ecosystem and wiring up projects. It triggers when starting a Sui project, porting code, or comparing SDK APIs. CX Codex +1 487installs frontend-apps The frontend-apps Claude Code skill guides frontend work on Sui browser apps. It covers wallet connections, on-chain queries, and transaction flows. CX Codex +1 479installs sui-client sui-client — a skill for Claude Code and Codex that handles Sui CLI setup, address management, and faucet tokens. Triggers on network switches, coin merges, or gas coin errors. CX Codex +1 403installs sui-overview The sui-overview Claude Code skill explains Sui’s design and ecosystem. It activates for blockchain comparisons, Sui architecture planning, and questions about moving from Ethereum or Solana. CX Codex +1 400installs sui-publish sui-publish — a skill for Claude Code deploys, tests, and upgrades Sui Move smart contract packages. Triggers on requests to publish packages, manage UpgradeCap, or troubleshoot dry run deployment failures. CX Codex +1 399installs generate-sui-agent-config generate-sui-agent-config — a skill for Claude Code and Codex generates CLAUDE.md or AGENT.md config files in Sui projects. Triggers when starting a new repo or when agent instructions are missing. CX Codex +1 391installs

Project sponsors

Companies that keep this analytics open