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
npx skills add MystenLabs/skills --skill walrus-sites -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/walrus-sites/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/walrus-sites/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill walrus-sites -a codex2Manually: put the files in place
.agents/skills/walrus-sites/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill walrus-sites -a cursor2Manually: put the files in place
.cursor/skills/walrus-sites/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install MystenLabs/skills walrus-sites2Manually: put the files in place
.github/skills/walrus-sites/SKILL.md1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill walrus-sites -a gemini-cli2Platform CLI
gemini skills install https://github.com/MystenLabs/skills --path walrus-sitesManually: put the files in place
.devin/skills/walrus-sites/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill walrus-sites -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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