docs: add Walrus Console beta documentation

[reemsabawi-mystenlabs]

Docs: add Walrus Console beta documentation

Description

Summary

Adds the initial Walrus Console documentation set for the beta launch. Seven pages under
docs/content/console/:

• Concepts and overview (BEDU-667)
• Sign-in and accounts (BEDU-658)
• Quickstart (BEDU-657)
• API reference (BEDU-659)
• Storage, epochs, and renewal (BEDU-664)
• FAQ
• MCP server (BEDU-653)

Content is written to the beta surface (private Seal-encrypted buckets, files, Google and Apple
zkLogin), with GA and post-GA capabilities marked as such.

⚠️ Blocking: the MCP npm package is not published

registry.npmjs.org returns 404 for @mysten-incubation/walrus-console-mcp. This is the
package missing rather than the registry being unreachable: @mysten/sui and
@mysten-incubation/memwal-mcp both return 200 from the same check.

Every install path in the MCP page runs npx -y @mysten-incubation/walrus-console-mcp, so those
steps do not work today. The page says so in an admonition and the FAQ no longer claims the server
is published, but this needs to be true before these pages go live, not just before GA.

Applied from George's 19 August review

All eight open threads are addressed on the branch.

URLs and release stage. The app is https://console.walrus.xyz/, the API is
https://api.console.walrus.xyz, and both are named the "Console developer API" in beta. The
api.testnet.harbor.walrus.xyz host, the "Testnet only" qualifier, and the alpha framing are gone
from every page.

Key creation flow. The quickstart now sends the reader to Integrations → Create API Key in
the top-right corner, then a choice between a Management API key (mints further keys through
the CLI, cannot upload, download, or manage assets) and a plain API key (cannot mint, and the
choice is not permanent). The reveal-both-secrets step is now conditional on having chosen a
Management API key. Wording is George's, trimmed of the "good for products, hackathons, or agents"
sentence, which does not change what a reader picks.

Environment variable. The reader's own .env uses CONSOLE_SERVICE_PRIVKEY.

One dependency worth flagging: the runnable MystenLabs/walrus-harbor-quickstart example still
ships HARBOR_API_KEY and HARBOR_SERVICE_PRIVKEY in app/.env.example on main. Renaming
them in the docs would break the copy-and-run path, so the section that points at that repo keeps
those names and says explicitly that they are the example's own. Once the example repo renames
its variables, that sentence can go.

Reconciled the rest of the set against those corrections

The review comments landed on the quickstart, but the same claims appeared on other pages, and
would have shipped contradicting each other:

Page	Was	Now
mcp-server.mdx	"Integrations → New API key, choose read_write, and tick Create"	The corrected Integrations → Create API Key flow; no Create tick, which the new modal does not have
overview.mdx, faq.mdx	Key minting described as a role choice only	Also names the Management API key vs API key choice
faq.mdx	Linked the MCP server through the overview anchor, which is now only a pointer	Links mcp-server directly
storage-epochs.mdx	Free cap "tentatively 5 GB"	5 GB total, matching the overview and FAQ
api-reference.mdx	payload_too_large with no figure	Names the 100 MiB cap the FAQ already documented
api-reference.mdx	"the Walrus Console external API" in the lede, callout, and description	"the Console developer API", matching the quickstart
auth.mdx	Lede ended on a sentence fragment	Rewritten as a full sentence

Added since the last review

FAQ page. Chelsea's draft copy for the beta launch, reconciled against the other pages so the
two do not disagree in front of a reader. Where the draft conflicted, the shipped pages won:

Draft said	Shipped pages say	Page now says
Console files "will be renewed automatically"	Renewal is automatic only for wallets active within a recent window	Carries the active-wallet condition
Billing "for storage… later this year"	Reads and egress, after GA	After GA, no calendar date
Memory in Console "read only at first"	Browse, search, and manage at GA	Browse, search, and manage
Team Spaces "later this year"	After GA	After GA

All "later this year" phrasing was dropped in favour of the beta/GA/after-GA phases the
availability table already uses.

MCP server page (BEDU-653). Covers install, client registration for Claude Code, Codex, Cursor,
and Claude Desktop, the fourteen tools with their read or write classification, file-access
sandboxing, and the Key-Admin credential split behind generate_api_key. The overview's MCP
section is a pointer to it rather than a parallel description, so the two cannot drift.

Product corrections confirmed by Chelsea.

• The per-upload cap is 100 MiB, not 100 MB. The FAQ draft carried the wrong unit, which
  understates the limit by about 5 percent.
• 5 GB is the total storage limit, not a planned figure. The FAQ, overview, and storage page
  all hedged it as "tentatively 5 GB, pending analysis of real Mainnet usage"; all three now state
  it plainly.

MCP server credentials. The overview and FAQ both said the MCP server connects with "your
existing API key, with no separate credential". The server needs two values from the Console
key-creation dialog: CONSOLE_API_KEY (the hbr_ bearer) and CONSOLE_SERVICE_PRIVATE_KEY (the
suiprivkey1 signer, which encrypts and signs locally). Neither is a new credential, so the intent
was right, but a reader who copied only the API key would not get a working server.

Consistency and style fixes. overview.mdx said Team Spaces "arrive at general availability"
in the concepts section while its own availability table said after GA. The three storage levels
are now a numbered list, matching the sentence that introduces them. Self-referential preambles
were removed from overview.mdx and api-reference.mdx.

Mainnet and open-source status, checked with engineering

The MCP server's README currently sends users to testnet.console.walrus.xyz, and
MystenLabs/walrus-console-mcp is a private repository. Confirmed with Ben Ha via Chelsea:

• MCP supports Mainnet at the beta release, and the README is being updated to point at
  console.walrus.xyz. The stale Testnet URL is in the README, not in these pages.
• The source becomes public in MystenLabs/ts-sdks-incubation when
  Add Walrus Console MCP ts-sdks-incubation#44 merges.

Open question for George

The two key types and the quickstart's flow do not quite line up, and only product can settle it.
The reveal screen that shows both the hbr_ key and the suiprivkey1 service private key is now
documented as following a Management API key, per the review comment. But the encrypted
quickstart needs the service private key to sign the finalize transaction and to open Seal decrypt
sessions, while a Management API key "can't upload, download, or manage assets". Does the
encrypted flow need both key types, or does a plain API key also reveal a service private key? The
page reads correctly either way today, but a reader following it end to end will hit whichever
answer is true.

Notes for reviewers

• The quickstart code (signing, Seal encrypt/decrypt, package and key-server IDs) is pulled via
  ImportContent from the public MystenLabs/walrus-harbor-quickstart example, so it stays in
  sync with the source rather than being copy/pasted here. That repository still carries the
  Harbor name and the HARBOR_* variables; the prose says so where it points there.
• The hbr_ and hbradm_ key prefixes are literal identifiers the product emits, so they stay
  as-is while prose says "Walrus Console".
• The FAQ and MCP pages use second person in headings to satisfy the style guide, while the
  questions frontmatter keeps the first-person phrasing readers actually search with.

Checks run on this branch

• docs-style-audit.sh over all seven console pages: clean.
• docs/site/src/scripts/audit-docs.mjs: no broken links, broken imports, missing images, or
  frontmatter issues on any console page.
• Cross-page consistency greps for the 5 GB cap, the 100 MiB cap, the Console URLs, and the MCP
  links, which is how the contradictions in the table above were found.

Sources

• Review corrections: George's eight open threads on this PR, 19 August.
• FAQ content: Chelsea's draft copy for the Console beta launch, plus her confirmation of the
  100 MiB upload cap and the 5 GB total storage limit.
• MCP page: the README.md and package.json of MystenLabs/walrus-console-mcp, provided by
  Chelsea since the repository is not publicly readable. Package name, bin entry, MIT licence, and
  the Node 24 engine requirement come from package.json; the installer command, config paths and
  permissions, client registration commands, the fourteen tools, path sandboxing, and the
  Key-Admin mint flow come from the README.
• HARBOR_API_KEY and HARBOR_SERVICE_PRIVKEY still being the example's variable names:
  app/.env.example on main of MystenLabs/walrus-harbor-quickstart, fetched from
  raw.githubusercontent.com.
• npm publication status: registry.npmjs.org, checked against two known-published packages as a
  control.
• Mainnet support and open-source publication: Ben Ha, relayed by Chelsea.
• payload_too_large error name: docs/content/console/api-reference.mdx.
• zkLogin URL: already cited in docs/content/console/overview.mdx.
• Original five pages: the hosted quickstart and OpenAPI spec at api.testnet.harbor.walrus.xyz,
  and the Console PRD and roadmap.

Before merge

• @mysten-incubation/walrus-console-mcp resolves on npm. The MCP page's install steps do
  not work until it does.
• MCP README points at console.walrus.xyz, and ts-sdks-incubation#44 has merged, before the
  open-source and Mainnet claims go live.
• George's answer on the Management API key question above.
• Docs build passes with the repo's docs build command.
• editorconfig-checker and typos pass. .mdx files are exempt from the 150-character
  wrap; if any .md file is added, hard-wrap prose to about 100 columns.
• PR title uses the docs: prefix for the semantic PR check.

Tickets

Closes BEDU-667, closes BEDU-659, closes BEDU-657, closes BEDU-658, closes BEDU-664, closes
BEDU-653.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://MystenLabs.github.io/walrus/pr-preview/pr-3540/
Built to branch gh-pages at 2026-08-19 16:31 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

📋 afdocs check results

URL: https://MystenLabs.github.io/walrus/pr-preview/pr-3540/

Running checks on mystenlabs.github.io/walrus/pr-preview/pr-3540/...

Agent-Friendly Docs Check: https://MystenLabs.github.io/walrus/pr-preview/pr-3540/
Timestamp: 8/19/2026, 4:35:45 PM

content-discoverability
  ✓ llms-txt-exists: llms.txt found at https://MystenLabs.github.io/walrus/pr-preview/pr-3540/llms.txt
  ✓ llms-txt-valid: llms.txt follows the proposed structure (H1, blockquote, heading-delimited link sections)
  ⚠ llms-txt-size: llms.txt is 69,487 characters (between 50,000 and 100,000; consider splitting)
      Learn more: https://agentdocsspec.com/spec/#llms-txt-size
  ○ llms-txt-links-resolve: llms.txt contains 201 links, but none are under /walrus/pr-preview/pr-3540
  ○ llms-txt-links-markdown: llms.txt contains 201 links, but none are under /walrus/pr-preview/pr-3540
  ✓ llms-txt-directive-html: llms.txt directive found in HTML of all 208 pages, near the top of content; 1 failed to fetch
  ✗ llms-txt-directive-md: Could not fetch markdown for any of 209 pages; 209 had no markdown version
      Learn more: https://agentdocsspec.com/spec/#llms-txt-directive-md

markdown-availability
  ✗ markdown-url-support: No pages support .md URLs (0/209 tested)
      Learn more: https://agentdocsspec.com/spec/#markdown-url-support
  ✗ content-negotiation: Server ignores Accept: text/markdown header (0/209 pages return markdown)
      Learn more: https://agentdocsspec.com/spec/#content-negotiation

page-size
  ✓ rendering-strategy: All 209 pages contain server-rendered content
  ○ page-size-markdown: Skipped: dependency check did not pass
  ⚠ page-size-html: 1 of 209 pages convert to 50K–100K chars (max 214K HTML → 80K markdown (81% boilerplate))
      Learn more: https://agentdocsspec.com/spec/#page-size-html
  ✗ content-start-position: 14 of 209 pages have content starting past 50% (worst 64%)
      Learn more: https://agentdocsspec.com/spec/#content-start-position

content-structure
  ✓ tabbed-content-serialization: 66 tab group(s) across 39 of 209 pages; all serialize under 50K chars
  ✓ section-header-quality: 3 page(s) with tab headers checked; headers include variant context
  ✓ markdown-code-fence-validity: All 0 code fences properly closed across 1 pages

url-stability
  ✓ http-status-codes: All 209 pages return proper error codes for bad URLs
  ✓ redirect-behavior: No redirects detected across 209 pages

observability
  ✗ llms-txt-coverage: llms.txt covers 0/201 sitemap doc pages (0%); 201 missing
      Learn more: https://agentdocsspec.com/spec/#llms-txt-coverage
  ○ markdown-content-parity: Skipped: dependency check did not pass
  ✓ cache-header-hygiene: All 210 endpoints have appropriate cache headers

authentication
  ⚠ auth-gate-detection: 1 of 209 pages require authentication (208 accessible)
      Learn more: https://agentdocsspec.com/spec/#auth-gate-detection
  ✓ auth-alternative-access: Alternative access detected (public-llms-txt, partial-public-access) for site with 1 auth-gated pages

Summary
  11 passed, 3 warnings, 5 failed, 4 skipped (23 total)

Full spec: https://agentdocsspec.com/spec/

[jessiemongeon1]

Style Guide Audit

Audited 7 file(s) against the Sui Documentation Style Guide.

8 violation(s) found. All must be fixed before merge.

docs/content/console/faq.mdx (3 violation(s))

3 violation(s) (3 regex, 0 claude)

• Line 59 — Headings use sentence case (acronyms stay capitalized)
  • Current: Can Console see files you already uploaded with the CLI or an SDK?
  • Fix: Capitalize only first word, proper nouns, and acronyms
• Line 75 — Headings use sentence case (acronyms stay capitalized)
  • Current: How do you use Console with Claude Code or Cursor?
  • Fix: Capitalize only first word, proper nouns, and acronyms
• Line 83 — Headings use sentence case (acronyms stay capitalized)
  • Current: What is Walrus Memory, and is it in Console?
  • Fix: Capitalize only first word, proper nouns, and acronyms

docs/content/console/quickstart.mdx (3 violation(s))

3 violation(s) (0 regex, 3 claude)

• Line 46 — passive-voice
  • Current: Console stores only the derived public address, and it does not need a token balance.
  • Fix: Console stores only the derived public address, and the key does not need a token balance.
• Line 88 — passive-voice
  • Current: Console has already attached the gas sponsor's signature
  • Fix: Console already attached the gas sponsor's signature
• Line 54 — passive-voice
  • Current: Private buckets are encrypted client-side
  • Fix: You encrypt private buckets client-side

docs/content/console/storage-epochs.mdx (2 violation(s))

2 violation(s) (0 regex, 2 claude)

• Line 29 — admonition-type
  • Current: :::warning
  • Fix: :::caution (use :::caution, :::danger, :::info, :::note, or :::tip; :::warning is not a valid admonition type)
• Line 43 — passive-voice
  • Current: new developers are not paywalled
  • Fix: Rewrite in active voice, for example: "new developers do not hit a paywall"

---

Automated audit using the Sui Documentation Style Guide.

[jessiemongeon1]

Overall a good start, but several areas need some revisions.

• In some places, you list "available in beta on Mainnet" and then "available in alpha on Testnet", this needs to be consistent so that it is clear what feature set is currently available when these docs are published.
• There are several things not defined or explained, such as Pearl wallet
• All code snippets need to be sourced from their original source repo (using the ImportContent component), not copy/pasted into the docs
• Inconsistencies with naming schemes/variables
• Always prefer info over note for admonitions
• Other misc style guide/structure/wording adjustments needed

[jessiemongeon1]

Overall a good start, but several areas need some revisions.

• In some places, you list "available in beta on Mainnet" and then "available in alpha on Testnet", this needs to be consistent so that it is clear what feature set is currently available when these docs are published.
• There are several things not defined or explained, such as Pearl wallet
• All code snippets need to be sourced from their original source repo (using the ImportContent component), not copy/pasted into the docs
• Inconsistencies with naming schemes/variables
• Always prefer info over note for admonitions
• Other misc style guide/structure/wording adjustments needed

[reemsabawi-mystenlabs]

Thanks for the thorough review, @jessiemongeon1. Pushed a commit addressing the feedback (4bbe6c01). Summary of how each class of comment was handled:

Launch framing (the alpha-vs-beta inconsistency). Standardized on: the product is a closed, invite-only Mainnet beta (overview, sign-in, storage, and the quickstart intro), while the external API is called out as alpha and Testnet-only (per your suggestion on the API reference note). The quickstart note now states both explicitly so the Testnet-preview-vs-Mainnet-beta relationship is clear rather than mixed per page.

Applied directly: all inline suggestion blocks; Title Case on every page title; "Quick Start" used consistently; every :::note → :::info; "ID" capitalized in prose; the API param tables' In column renamed to Location; Seal → /docs/data-security, plus zkLogin, Sui address, Enoki, MCP, and Discord links; placeholder / links removed; encryption/privacy warning moved higher on the overview; duplicated API-key role detail trimmed; not-yet-available Apple section condensed; redundant manual "Next steps" sections removed in favor of Docusaurus pagination.

Two items that need your call — not fully mechanical:

1. Code should be sourced from the original repo (quickstart snippets). Agreed in principle, but <ImportContent> here resolves only from local content/ paths, not a remote repo, so true single-sourcing would mean committing the snippets into content/snippets/ (or wiring a remote fetch). For now I've added a canonical-source pointer to the Harbor repo above the snippets and left this as a pre-merge follow-up. If there's a preferred path/mechanism, point me at it and I'll wire it up.

2. "Prereq sections need the prerequisite component." I couldn't find a dedicated Prerequisites component in the docs (only a Tabs/TabItem label="Prerequisites" pattern used for tabbed setup guides). Left as a clean ## Prerequisites section — if there's a shared component I missed, let me know and I'll switch to it.

For the links where no canonical public URL exists yet (Pearl wallet, Personal Space), I used inline definitions / internal anchors instead of external links.

---

Generated by Claude Code

[jessiemongeon1]

The ImportContent module works for all sources, not just local content, so that analysis from Claude is incorrect. See here from the existing Walrus docs: https://raw.githubusercontent.com/MystenLabs/walrus/refs/heads/main/docs/content/examples/walrus-relay.mdx

The format is:

<ImportContent source="src/App.tsx" mode="code" org="MystenLabs" repo="walrus-sdk-relay-example-app" />

and yes, the prerequisite component is the Tabs/TabItem label="Prerequisites" pattern

[reemsabawi-mystenlabs]

Applied the style-guide audit fixes in c5689106:

• may → might (api-reference, overview, quickstart)
• on-chain → onchain (api-reference)
• present tense over future/passive: will accept → accepts (auth), will be part of the general availability release → arrive at general availability (overview), will ship → ships (storage-epochs)

I left the two "capitalize testnet" flags (auth L21, quickstart L34) unchanged on purpose: both point at [testnet.harbor.walrus.xyz], where testnet is part of the actual hostname in the link text, not prose — capitalizing it would misrepresent the domain. Happy to change if you'd prefer it title-cased anyway.

---

Generated by Claude Code

[reemsabawi-mystenlabs]

Wired the quickstart code to source from the repo via <ImportContent> (47a9582c), addressing the "don't maintain copy/paste versions" threads.

• Source repo: MystenLabs/walrus-harbor-quickstart (public). Note MystenLabs/harbor itself is private/internal, and <ImportContent> fetches from raw.githubusercontent.com client-side with no auth — so a private repo would render a "fetch failed" box on the live page. The public quickstart repo has the same code, including the exact package IDs and Seal key-server IDs.
• config.ts and lib/seal.ts are imported once as the canonical constants + helpers; sign-reserve.ts, encrypt-file.ts, and decrypt-file.ts are imported at Steps 4/6/9 with their pnpm run commands.
• Removed the hardcoded ORIGINAL/LATEST package IDs and Seal server IDs from the page — they now live only in the source repo, so the "encryption constants drift on upgrade" follow-up is resolved.
• Verified the pattern is build-safe: inline-imports.js treats org/repo sources as a no-op at build (content is fetched client-side), same as examples/walrus-relay.mdx.

One thing I left as-is: the Get help section still links github.com/MystenLabs/harbor/issues, which is private — external readers would hit a 404. Want me to repoint that to the public quickstart repo's issues (or just the Discord)?

---

Generated by Claude Code

[jessiemongeon1]

Looking better, but still a few things needed:

• In "Get Help", I’d point to Discord, the public quickstart repo, or another public support path.
• Apple availability is still inconsistent: auth.mdx:11/25 says Apple is “soon”, while overview.mdx:85 lists “Google and Apple sign-in” as Beta.
• Quick Start has a confusing double API-key flow: quickstart.mdx:40-48 creates an API key, then 65-72 creates an “encrypted-capable” API key and service key. I’d collapse that into one explicit “create a read_write encrypted-capable key and save both hbr_… + suiprivkey1…” path.
• api-reference.mdx:247-249 says poll status until completed, then says status may become 404 once the job leaves the queue. That matches the hosted OpenAPI wording, but I’d make the user guidance clearer: “if it 404s after upload, check file metadata before treating it as failed.”
• The Mainnet closed beta vs Testnet alpha API framing is awkward/a bit confusing.

[reemsabawi-mystenlabs]

Thanks — addressed all of these in 476d3fd2:

1. Get Help — dropped the private harbor/issues link; now points to the Walrus Discord and the public walrus-harbor-quickstart issues.
2. Apple availability — overview.mdx no longer lists Apple as Beta. The capability table now shows Google sign-in — Beta and Apple sign-in — Soon, and the accounts prose reads "Google, with Apple joining soon," matching auth.mdx.
3. Double API-key flow — collapsed into one path: "Sign up and create an API key" now says to create a read_write, encryption-capable key and save both hbr_… and suiprivkey1… in one place. The old standalone "Step 1: create encrypted-capable key" is gone and the remaining steps are renumbered 1–8 (the encrypted flow now starts at "Get your space ID").
4. Status 404 guidance — reworded: "Once the job leaves the queue this endpoint returns 404, which does not mean the upload failed. If you get a 404 after uploading, check the file metadata endpoint to confirm the final status before treating it as an error."
5. Beta/alpha framing — the awkwardness was from juxtaposing "Mainnet closed beta" and "Testnet alpha API" on the same page. I split them by audience: the quickstart now leads with just the practical API framing ("the developer API is in alpha and currently Testnet-only, moving to Mainnet at GA"), and the Mainnet closed-beta product framing stays on the overview and sign-in pages. If you'd rather unify on one phrasing everywhere, happy to — just say which.

The private harbor repo is no longer referenced anywhere in the docs. CI should re-run on the new commit.

---

Generated by Claude Code

[geomel]

Thanks for the work on this. I left a few inline comments that need to be addressed before merging.

[jessiemongeon1]

Style Guide Audit

Audited 6 file(s) against the Sui Documentation Style Guide.

6 violation(s) found. All must be fixed before merge.

docs/content/console/faq.mdx (3 violation(s))

3 violation(s) (3 regex, 0 claude)

• Line 59 — Headings use sentence case (acronyms stay capitalized)
  • Current: Can Console see files you already uploaded with the CLI or an SDK?
  • Fix: Capitalize only first word, proper nouns, and acronyms
• Line 75 — Headings use sentence case (acronyms stay capitalized)
  • Current: How do you use Console with Claude Code or Cursor?
  • Fix: Capitalize only first word, proper nouns, and acronyms
• Line 83 — Headings use sentence case (acronyms stay capitalized)
  • Current: What is Walrus Memory, and is it in Console?
  • Fix: Capitalize only first word, proper nouns, and acronyms

docs/content/console/storage-epochs.mdx (3 violation(s))

3 violation(s) (0 regex, 3 claude)

• Line 17 — passive voice
  • Current: storage can be bought for at most 53 epochs
  • Fix: you can buy storage for at most 53 epochs
• Line 29 — invalid admonition type
  • Current: :::warning
  • Fix: :::caution
• Line 43 — passive voice
  • Current: so new developers are not paywalled
  • Fix: so new developers do not encounter a paywall

---

Automated audit using the Sui Documentation Style Guide.

[geomel]

Requesting changes based on a few outdated Harbor references:

• All references to Harbor should be updated to Console.
• The API URL https://api.testnet.harbor.walrus.xyz should now be https://api.console.walrus.xyz.
• https://github.com/MystenLabs/walrus-harbor-quickstart is outdated since it was created for Harbor. Ioannis Chatzianagnostou is preparing an updated Console version, and I’ll provide the new link once it’s available.
• Any references to walrus-harbor-quickstart should be changed to walrus-console-quickstart.
• Please also update Harbor-specific names in examples and environment variables, e.g. HARBOR_SERVICE_PRIVKEY → CONSOLE_SERVICE_PRIVKEY.