# Walrus Docs > Walrus is a decentralized blob storage protocol built on Sui. It provides robust, cost-effective > storage for large binary objects with high availability guarantees using erasure coding. This > documentation covers setup, usage, the client CLI, SDKs, on-chain integration, and Walrus Sites > (decentralized web hosting). Important notes: - Walrus stores data as **blobs** (immutable byte arrays). All blobs are public; use an encryption service like Seal for private data. - Walrus has two networks: **Mainnet** (production, uses real SUI/WAL tokens) and **Testnet** (for development and testing). - The `walrus` CLI is the primary client. It supports storing, reading, and managing blobs, and can run as a local daemon exposing an HTTP API. - **Walrus Sites** enable fully decentralized web hosting: static assets stored on Walrus, with a Sui smart contract as the on-chain index. - Costs involve WAL tokens (for storage) and SUI tokens (for on-chain transactions). ## Getting Started - [Advanced Setup](https://docs.wal.app/docs/getting-started/advanced-setup.md): This page covers advanced setup options for Walrus, including building from source, installing from binaries, or using Cargo. For standard setup instructions, see Getting Started. Walrus is open source under an Apache 2 license. - [Getting Started](https://docs.wal.app/docs/getting-started.md): Walrus is a verifiable data platform for high-stakes systems like AI and onchain finance, where data is stored as blobs. Walrus uses an object storage architecture, where blobs are stored in a flat namespace rather than a hierarchy. There are no folders or directories. ## System Overview - [Available Networks](https://docs.wal.app/docs/system-overview/available-networks.md): Walrus Mainnet operates a production-quality storage network using corresponding resources on the Sui Mainnet. The Walrus Testnet operates in conjunction with the Sui Testnet and is used to test new features before they graduate to Mainnet. - [Core Concepts](https://docs.wal.app/docs/system-overview/core-concepts.md): Data is stored on Walrus as blobs. Each blob is an immutable array of bytes. Any type of file, such as text, video, or source code, can be stored on Walrus. All blobs uploaded to Walrus are publicly available. To secure data on Walrus, consider an encryption service like Seal. - [System Overview](https://docs.wal.app/docs/system-overview.md): Available Networks: Overview of Walrus networks including Mainnet and Testnet configurations, parameters, and setup instructions. Walrus Fundamentals: Technical reference for Walrus fundamentals, including architecture, data storage, and data retrieval. - [Operations](https://docs.wal.app/docs/system-overview/operations.md): Blobs can be interacted with through familiar file system operations such as uploading, reading, downloading, and deleting. Use the following command to upload a file to Walrus > Danger > > All blobs stored in Walrus are public and discoverable by all. - [Public Aggregators And Publishers](https://docs.wal.app/docs/system-overview/public-aggregators-and-publishers.md): The Walrus client offers a daemon mode that runs a simple web server that provides HTTP interfaces you can use to store and read blobs in an aggregator or publisher role respectively. - [Quilt](https://docs.wal.app/docs/system-overview/quilt.md): Quilt is a batch storage feature designed to optimize the storage cost and efficiency of large numbers of small blobs. Before Quilt, storing small blobs (less than 10 MB) on Walrus involved higher per-byte costs due to internal system data overhead. - [Red Stuff](https://docs.wal.app/docs/system-overview/red-stuff.md): The RedStuff encoding algorithm used in Walrus is an adaptation of the Twin-Code framework presented by Rashmi et al. [[1]](https://doi.org/10.1109/ISIT.2011.6033732). - [Relay](https://docs.wal.app/docs/system-overview/relay.md): An upload relay is a server-side service that simplifies the upload process by handling the complexity of writing to multiple storage nodes. It provides batching capabilities and improved reliability for client applications. - [Storage Costs](https://docs.wal.app/docs/system-overview/storage-costs.md): When choosing a platform to store and verify data, you should consider reliability, uptime, availability, programmability, and price predictability. Walrus offers a fixed, USD-denominated storage cost of $0.023/GB/month, allowing you to budget and scale with confidence. - [System Constraints](https://docs.wal.app/docs/system-overview/system-constraints.md): This page describes the practical limits and constraints you should consider when designing applications on Walrus. For current values, run walrus info. Walrus supports blobs up to approximately 13.6 GiB. Check the current limit with walrus info under "Maximum blob size. - [View System Info](https://docs.wal.app/docs/system-overview/view-system-info.md): The Walrus system object contains metadata about available and used storage and the price of storage per KiB in FROST. These values are determined by 2/3 agreement between storage nodes for each storage epoch. You can pay to purchase storage space for specified durations. ## Walrus Client - [Walrus Client](https://docs.wal.app/docs/walrus-client.md): JSON Mode: Use JSON mode for programmatic access to all Walrus CLI commands with JSON-formatted input and output. Managing Blobs: Use the Walrus client to extend, delete, burn, share, and set attributes on blobs. - [JSON Mode](https://docs.wal.app/docs/walrus-client/json-mode.md): All Walrus client commands are available in JSON mode, which simplifies programmatic access to the CLI. You can specify all command-line flags of the original CLI command in JSON format. - [Managing Blobs](https://docs.wal.app/docs/walrus-client/managing-blobs.md): Use the Walrus client to manage blobs and their metadata. You can extend Walrus blob lifetimes using the following command: The blob cannot be expired when you run this command. Both address-owned blobs and shared blobs can have their lifetime extended. - [Quilts](https://docs.wal.app/docs/walrus-client/quilts.md): For efficiently storing large numbers of small blobs, Walrus provides the quilt feature. A quilt batches multiple blobs into a single storage unit, significantly reducing overhead and cost. Learn more about quilts. You can interact with quilts using a dedicated set of walrus subcommands. - [Reading Blobs](https://docs.wal.app/docs/walrus-client/reading-blobs.md): You can query the status of a blob through one of the following commands: Each command returns output that indicates whether the specified blob is stored and its availability period. - [Storing Blobs](https://docs.wal.app/docs/walrus-client/storing-blobs.md): All blobs stored in Walrus are public and discoverable by all. To store sensitive data, use Seal or Nautilus to encrypt the data before storing it on Walrus. - [Walrus CLI](https://docs.wal.app/docs/walrus-client/walrus-cli.md): Use the command-line interface (CLI) to interact with the Walrus client. The CLI is available by installing the walrus binary. ## HTTP API - [Quilt HTTP APIs](https://docs.wal.app/docs/http-api/quilt-http-apis.md): Walrus supports storing and retrieving multiple blobs as a single unit called a quilt. Publishers and aggregators both support quilt operations. All query parameters available for storing regular blobs can also be used when storing quilts. - [Reading Blobs](https://docs.wal.app/docs/http-api/reading-blobs.md): You can read blobs using HTTP GET requests with their blob ID or object ID. > Reading a blob right after upload? > > When you read through a CDN-fronted aggregator immediately after certification, the CDN might briefly cache a 404 from before the blob propagated. - [Storing Blobs](https://docs.wal.app/docs/http-api/storing-blobs.md): > No public Mainnet publisher > > Walrus has no public unauthenticated publisher on Mainnet. There are no plans to create one. On Mainnet, run your own authenticated publisher (or use the Upload Relay or TypeScript SDK directly). ## TypeScript SDK - [SDKs](https://docs.wal.app/docs/typescript-sdk/sdks.md): Mysten Labs has built and published a Walrus TypeScript SDK, which supports a wide variety of operations. See also the related examples. The Walrus core team is actively working on a Rust SDK for Walrus. For data security, use the TypeScript SDK for Seal. ## Examples - [Checkpoint Data](https://docs.wal.app/docs/examples/checkpoint-data.md): The Sui Archival application demonstrates how Sui blockchain checkpoint data can be archived on Walrus in a reliable, deterministic, and resilient manner. The application is accessible at https://walrus-sui-archival.wal.app/ The application's code is open source and available on GitHub. - [Examples](https://docs.wal.app/docs/examples.md): Example applications that demonstrate different workflows and use cases on Walrus Sui Archival System: An example application that demonstrates archiving Sui blockchain checkpoint data on Walrus. - [Javascript](https://docs.wal.app/docs/examples/javascript.md): The following JavaScript example shows how to upload and download a blob through a web form using the HTTP API. - [Move](https://docs.wal.app/docs/examples/move.md): The following Move example showcases how to import and use Walrus onchain objects. - [Python](https://docs.wal.app/docs/examples/python.md): You can interact with Walrus from within Python code. Use the HTTP API to store and read blobs. Use the JSON API to store, read, and check the availability of a blob. Checking the certification of a blob illustrates reading the blob's corresponding Sui object. - [Walrus Relay](https://docs.wal.app/docs/examples/walrus-relay.md): Using the Walrus TypeScript SDK and the Walrus Upload Relay, the following example app creates a web application that can be used for uploading and managing blobs on Walrus. View a deployed instance of this example in your browser or view the entire source code. ## Operator Guide - [Operating Aggregator](https://docs.wal.app/docs/operator-guide/aggregators/operating-aggregator.md): Run a Walrus aggregator to expose the HTTP API. - [Operator Guide](https://docs.wal.app/docs/operator-guide.md): Service providers on Walrus host network services such as storage nodes, aggregators, and publishers. Aggregator and Publisher Limitations: Request size limits, nginx caching configuration, and daemon metrics for Walrus aggregators and publishers. - [Limitations](https://docs.wal.app/docs/operator-guide/limitations.md): By default, store blob requests are limited to 10 MiB. You can increase this limit through the --max-body-size option. Store quilt requests are limited to 100 MiB by default, and you can increase them using the --max-quilt-body-size option. - [Auth Publisher](https://docs.wal.app/docs/operator-guide/publishers/auth-publisher.md): The authenticated publisher requires HTTP requests to store a blob to be authenticated. Use an authenticated publisher as a building block for services that need to store data over HTTP on Walrus Mainnet, where an open publisher is undesirable because of the SUI and WAL cost of publishing to Walrus. - [Mainnet Production Guide](https://docs.wal.app/docs/operator-guide/publishers/mainnet-production-guide.md): Walrus does not provide a public unauthenticated publisher on Mainnet. There are no plans to create one because the publisher must pay SUI and WAL for every blob it stores. On Mainnet, a publisher should be privately operated for a specific application, service, or organization. - [Operating Publisher](https://docs.wal.app/docs/operator-guide/publishers/operating-publisher.md): The publisher and daemon perform onchain actions and require a Sui wallet with sufficient SUI and WAL balances. To handle many parallel requests without object conflicts, they create internal sub-wallets (introduced in version 1.4.0) funded from the main wallet. - [Signed Binaries](https://docs.wal.app/docs/operator-guide/signed-binaries.md): Walrus release binaries and Docker images are signed using Cosign with a GCP KMS key. Each binary has a corresponding .sig file containing its signature. Docker image signatures are stored in the registry. - [Stake](https://docs.wal.app/docs/operator-guide/stake.md): In Walrus, anyone can delegate stake to storage nodes and, by doing so, influence which storage nodes get selected for the committee in future epochs and how many shards these nodes hold. - [Backup Restore Guide](https://docs.wal.app/docs/operator-guide/storage-nodes/backup-restore-guide.md): Walrus storage nodes provide backup and restore functionality for the primary database containing blob data. This guide covers configuration requirements, operational procedures, and best practices for automated and manual backup processes and restore operations. - [Commission Governance](https://docs.wal.app/docs/operator-guide/storage-nodes/commission-governance.md): You can change most node parameters using StorageNodeCap, and the storage node automatically updates them based on the values in the node configuration. However, authorization for contract upgrades and withdrawing the storage node commission is handled separately. - [Storage Nodes](https://docs.wal.app/docs/operator-guide/storage-nodes.md): This section covers everything you need to set up and operate a Walrus storage node. Backup and Restore Guide: Back up and restore Walrus storage node databases with automated and manual procedures. - [Slashing Walkthrough](https://docs.wal.app/docs/operator-guide/storage-nodes/slashing-walkthrough.md): This page walks through a hypothetical slashing event on Mainnet so you can see how the pieces fit together. It assumes you have already read Slashing for the conceptual model and the object IDs. The commands below are the ones operators actually run, with the live Mainnet object IDs filled in. - [Slashing](https://docs.wal.app/docs/operator-guide/storage-nodes/slashing.md): Walrus protects the network from misbehaving storage nodes through an onchain slashing mechanism. Committee members vote against a candidate node, and when a quorum of voting weight is reached, anyone can finalize the slashing to burn the candidate's accumulated commission. - [Storage Node FAQ](https://docs.wal.app/docs/operator-guide/storage-nodes/storage-node-faq.md): The storage node must have a wallet compatible with the Sui Rust SDK. This cannot be a hardware wallet or anything that requires user interaction for transactions, because the node needs to send transactions as part of normal operation. The walrus-node setup command creates such a wallet. - [Storage Node Maintenance](https://docs.wal.app/docs/operator-guide/storage-nodes/storage-node-maintenance.md): This page covers the ongoing operation of your Walrus storage node after initial setup. Back up the /opt/walrus/config directory. For database backups, see the Backup and Restore Guide. The following metrics are the most important for monitoring node health. - [Storage Node Migration](https://docs.wal.app/docs/operator-guide/storage-nodes/storage-node-migration.md): This guide covers migrating a Walrus storage node to new hardware. It assumes you run the node (and optionally an aggregator and publisher) on the same host. [x] New host set up following the Storage Node Setup guide (through the TLS setup and systemd service sections. - [Storage Node Setup](https://docs.wal.app/docs/operator-guide/storage-nodes/storage-node-setup.md): This page walks you through the full initial setup of a Walrus storage node, from system preparation to registration and first startup. > Caution > > If you deviate from the standard setup below (user, directories, ports), make sure to adjust later steps accordingly. - [Upload Relay](https://docs.wal.app/docs/operator-guide/upload-relay.md): Walrus enables apps to store data from within end-user browsers that have low to moderate machine specifications (mobile devices, low-powered laptops, and so on). ## Sites - [Github Actions Workflow](https://docs.wal.app/docs/sites/ci-cd/github-actions-workflow.md): Create a GitHub Actions workflow to automatically deploy your Walrus Site whenever you push to your repository. The workflow uses the official Deploy Walrus Site action maintained by Mysten Labs. [x] A GitHub repository containing your site's source files. - [1. Reconstruct Sui client configuration from CI secrets.](https://docs.wal.app/docs/sites/ci-cd/other-ci-cd-platforms.md): The official Deploy Walrus Site action targets GitHub Actions only. On any other CI/CD platform, such as GitLab CI/CD, CircleCI, or Bitbucket Pipelines, you drive deployment directly through the site-builder CLI. - [Preparing Deployment Credentials](https://docs.wal.app/docs/sites/ci-cd/preparing-deployment-credentials.md): To deploy a Walrus Site through a GitHub Actions workflow, the workflow must sign Sui transactions on your behalf. This requires 2 credentials: a private key stored as an encrypted GitHub secret, and the corresponding Sui address stored as a GitHub variable. [x] Install the Sui binary. - [Adding Metadata](https://docs.wal.app/docs/sites/configuration/adding-metadata.md): The metadata section of ws-resources.json lets you add human-readable information to your Walrus Site object. This data is stored onchain and is used by portals, explorers, wallets, and other tools to display information about your site. - [Site Configuration](https://docs.wal.app/docs/sites/configuration/site-configuration.md): In its base configuration, a Walrus Site serves static assets through a portal. However, many modern web applications require more advanced features, such as custom headers, client-side routing, and human-readable information. - [Specifying HTTP Headers](https://docs.wal.app/docs/sites/configuration/specifying-http-headers.md): The headers section allows you to specify custom HTTP response headers for specific resources. The keys in the headers object are the exact paths of the resources (no wildcards), and the values are lists of key-value pairs corresponding to the headers that the portal attaches to the response. - [Bringing Your Own Domain](https://docs.wal.app/docs/sites/custom-domains/bringing-your-own-domain.md): By default, Walrus Sites are served through a portal at a subdomain address like https://example.wal.app. If you want to serve your site at a classic DNS domain you own, for example https://example.com, you can do so by deploying your own portal and configuring it to serve only your site. - [DNS Configuration](https://docs.wal.app/docs/sites/custom-domains/dns-configuration.md): After setting up your portal and configuring it for your domain, you need to configure your domain's DNS to route traffic to the server running your portal. This guide covers adding DNS records, setting up HTTPS with a reverse proxy, verifying propagation, and troubleshooting common DNS issues. - [Setting A SuiNS Name](https://docs.wal.app/docs/sites/custom-domains/setting-a-suins-name.md): Sui Name Service (SuiNS) provides human-readable names for Walrus Sites, similar to how DNS works for websites. Instead of sharing a long Base36 subdomain like , you can link a SuiNS name to your site's object ID and browse it at a readable address like my-project.wal.app. - [Installing The Site Builder](https://docs.wal.app/docs/sites/getting-started/installing-the-site-builder.md): The site-builder is a CLI tool that lets you create, edit, and publish Walrus Sites. You can install it using suiup or a pre-built binary. [x] Install a recent version of Rust. [x] Install and configure Walrus. > Warning > > The stable branch of Walrus Sites is mainnet. - [Publishing Your First Site](https://docs.wal.app/docs/sites/getting-started/publishing-your-first-site.md): The Walrus Sites site-builder uploads your website's files to Walrus, where resources like HTML, CSS, JavaScript, and images are stored as blobs. A Sui smart contract serves as an onchain index that maps each resource path to its Walrus blob ID and records site ownership. - [Using The Site Builder](https://docs.wal.app/docs/sites/getting-started/using-the-site-builder.md): This reference page provides details on site-builder configuration and CLI commands. - [Sites](https://docs.wal.app/docs/sites.md): Walrus Sites are decentralized websites built on Sui and Walrus. Your site's files are stored on Walrus, a decentralized storage network, while a Sui smart contract records ownership and maps each resource path to its content. - [Components](https://docs.wal.app/docs/sites/introduction/components.md): 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. - [Technical Overview](https://docs.wal.app/docs/sites/introduction/technical-overview.md): A Walrus Site is a static web site published entirely onchain, with no origin server. Sui stores the site's ownership and resource index, and Walrus stores the resource files themselves. A portal bridges these systems and serves the site to the browser over standard HTTP. - [Known Restrictions](https://docs.wal.app/docs/sites/known-restrictions.md): Walrus Sites can be used to deploy almost any form of traditional static Web2 website built for modern browsers. There are, however, a number of restrictions that developers should keep in mind when creating or porting a website to Walrus Sites. - [Avoiding Duplicate Content SEO](https://docs.wal.app/docs/sites/linking/avoiding-duplicate-content-seo.md): Duplicate content occurs when the same or substantially similar content is accessible at more than 1 URL. Search engines such as Google consolidate duplicate pages and assign ranking signals to whichever URL they consider canonical. - [Linking From Walrus Sites](https://docs.wal.app/docs/sites/linking/linking-from-walrus-sites.md): Walrus Sites serves content stored on Walrus through a portal. All relative URLs in your site resolve against the onchain site object. Anything outside that object, such as third-party pages, APIs, CDN assets, other Walrus Sites, requires an absolute URL. - [Linking To Walrus Sites](https://docs.wal.app/docs/sites/linking/linking-to-walrus-sites.md): A Walrus Site is addressed through a portal. The portal resolves the site from an onchain object and serves its content. To link to a Walrus Site from an external source, you construct a URL that the portal can resolve. - [Redirects](https://docs.wal.app/docs/sites/linking/redirects.md): Walrus Sites supports 3 kinds of redirects: internal routing redirects, HTTP redirects, and object redirects. Internal routing redirects map URL paths within your site to specific resources. HTTP redirects return 3xx responses to send the client to a different URL. - [Mainnet](https://docs.wal.app/docs/sites/portals/deploy-locally.md): To view a website deployed using Walrus Sites, you must use a Sites Portal. A portal retrieves site resources from Walrus and their corresponding Sui objects before serving the site in your browser. You can browse any Walrus Site deployed on Mainnet or Testnet using a Sites Portal. - [Uncomment and configure when enableallowlist is true](https://docs.wal.app/docs/sites/portals/mainnet-testnet.md): Walrus Site Portals are used to access and browse a Walrus Site. The portal you run must match the network on which your site is deployed. Each network has its own onchain package, default RPC endpoint, and Walrus aggregator. - [Access Control Options](https://docs.wal.app/docs/sites/security/access-control-options.md): All blobs stored on Walrus are public by default. Anyone who knows a blob ID can fetch its contents directly from a Walrus aggregator. This means that access control for Walrus Sites is not enforced at the storage layer. - [Site Data Authentication](https://docs.wal.app/docs/sites/security/site-data-authentication.md): Walrus Sites use SHA-256 hashes stored on Sui to verify that every resource served by a portal matches the content the site owner originally published. - [Troubleshooting](https://docs.wal.app/docs/sites/troubleshooting.md): This page covers common errors when deploying and browsing Walrus Sites, organized by where they occur. Errors in this section relate to site-builder configuration. Cause: The site-builder binary is not in a directory that your shell searches when running commands. ## Troubleshooting - [Error Handling](https://docs.wal.app/docs/troubleshooting/error-handling.md): This page covers how to handle Walrus errors programmatically in your applications. For a reference of specific error messages and their solutions, see Troubleshooting Common Errors. Not all errors are equal. - [Troubleshooting](https://docs.wal.app/docs/troubleshooting.md): Resolve common issues with the Walrus CLI, configuration, and network connectivity. Before undertaking any other steps, make sure you have the latest walrus binary. If you have multiple versions in different locations, find the binary that is actually used with which walrus. - [Network Errors](https://docs.wal.app/docs/troubleshooting/network-errors.md): This page covers common errors you might encounter when using Walrus. Each entry includes the error message, its cause, and how to troubleshoot it. Errors in this section occur when the Walrus CLI cannot load or parse its configuration. - [Reading Blobs After Upload](https://docs.wal.app/docs/troubleshooting/reading-blobs-after-upload.md): Walrus itself is strongly consistent. Once a blob is certified, any aggregator reading directly from storage nodes returns it immediately. Public aggregators often sit behind a content delivery network (CDN), which might cache a 404 Not Found response from before the aggregator sees the blob. ## Data Security - [Data Security](https://docs.wal.app/docs/data-security.md): Walrus provides decentralized storage for application and user data. All data stored on Walrus is public and can be accessed by anyone. ## Glossary - [Glossary](https://docs.wal.app/docs/glossary.md): This glossary defines key terms used throughout the Walrus documentation, covering storage concepts, erasure coding, cryptographic primitives, token economics, and network roles. Storage node: Entity storing data for Walrus; holds one or several shards. ## 01 Announcing Walrus - [01 Announcing Walrus](https://docs.wal.app/blog/01_announcing_walrus.md): Walrus is an innovative decentralized storage network for blockchain apps and autonomous agents. The Walrus storage system is being released today as a developer preview for Sui builders in order to gather feedback. We expect a broad rollout to other web3 communities very soon! ## 02 Devnet Update - [02 Devnet Update](https://docs.wal.app/blog/02_devnet_update.md): We have redeployed the Walrus Devnet to incorporate various improvements to the Walrus storage nodes and clients. In this process, all blobs stored on Walrus were wiped. Note that this may happen again on Devnet and Testnet, but obviously not on the future Mainnet. ## 03 Whitepaper - [03 Whitepaper](https://docs.wal.app/blog/03_whitepaper.md): In June, Mysten Labs announced Walrus, a new decentralized secure blob store design, and introduced a developer preview that currently stores over 12TiB of data. Breaking the Ice gathered over 200 developers to build apps leveraging decentralized storage. ## 04 Testnet Update - [04 Testnet Update](https://docs.wal.app/blog/04_testnet_update.md): Today, a community of operators launches the first public Walrus Testnet. This is an important milestone in validating the operation of Walrus as a decentralized blob store, by operating it on a set of independent storage nodes, that change over time through a delegated proof of stake mechanism. ## 05 Testnet Redeployment - [05 Testnet Redeployment](https://docs.wal.app/blog/05_testnet_redeployment.md): We are today redeploying the Walrus Testnet to incorporate various improvements, including some backwards-incompatible changes. Make sure to get the latest binary and configuration as described in the setup section. Note that all blob data on the previous Testnet instance has been wiped. ## 06 Mainnet - [06 Mainnet](https://docs.wal.app/blog/06_mainnet.md): The production Walrus Mainnet is now live, and operated by a decentralized network of over 100 storage nodes. Epoch 1 begun on March 25, 2025. ## Large Uploads - [Large Uploads](https://docs.wal.app/docs/large-uploads.md): The maximum blob size on Walrus is approximately 13.6 GiB. Uploading large data sets or individual blobs larger than 1 GiB require certain workarounds and planning for optimal performance and efficiency. After you plan your upload strategy, estimate the storage costs for your data. ## Walrus Memory - [Permanent Registry Design Intent](https://docs.wal.app/docs/walrus-memory/architecture/permanent-registry-design.md): The AccountRegistry shared object in Walrus Memory is designed as a permanent append-only mapping of . Even if a user decides to deactivate or "delete" their account, their address remains in the registry. - [Delegate Key Management](https://docs.wal.app/docs/walrus-memory/contract/delegate-key-management.md): Delegate keys are lightweight Ed25519 keys used for SDK authentication. They are registered onchain in a MemWalAccount and verified by the relayer on every request. - [Overview](https://docs.wal.app/docs/walrus-memory/contract/overview.md): The smart contract (memwal:account) defines the onchain account model for Walrus Memory. It is a Move module deployed on Sui. These are the onchain IDs for the current public Walrus Memory deployments: For relayer setup and environment variable usage, see Self-Hosting and Environment Variables. - [Ownership And Permissions](https://docs.wal.app/docs/walrus-memory/contract/ownership-and-permissions.md): The owner is the Sui wallet address that created the MemWalAccount. - [Docs Workflow](https://docs.wal.app/docs/walrus-memory/contributing/docs-workflow.md): Walrus Memory is still in beta, so documentation is an active part of product hardening. If you see unclear guidance, outdated flows, or missing examples, contributions are welcome. The docs source of truth is the markdown content under docs/ in this repository. - [Run Docs Locally](https://docs.wal.app/docs/walrus-memory/contributing/run-docs-locally.md): Run these commands from the repository root: This starts the Mintlify site using the docs in this repository. Use Node 20 LTS for Mintlify local preview. Mintlify fails on Node 25+. - [Docs site (Mintlify)](https://docs.wal.app/docs/walrus-memory/contributing/run-repo-locally.md): | Tool | Version | Check | |------|---------|-------| | Node.js | ≥ 20 | node -v | | pnpm | ≥ 9.12 | pnpm -v | | Rust | latest stable (only for backend services) | rustc --version | > Tip > > If you only work on TypeScript apps or docs, you don't need Rust. - [Example Apps](https://docs.wal.app/docs/walrus-memory/examples/example-apps.md): The repo includes ready-to-run apps in apps/ that show different Walrus Memory integration patterns. This page focuses on app-level patterns,the basic SDK flow covered in Quick Start and Walrus Memory Usage. Dashboard, playground, and interactive demo for Walrus Memory. - [Core Components](https://docs.wal.app/docs/walrus-memory/fundamentals/architecture/core-components.md): Walrus Memory is made up of six core components that work together to give your agents portable, verifiable memory that they fully control. The TypeScript SDK is the main entry point for developers. It wraps all Walrus Memory operations into a basic client that your app calls directly. - [Data Flow Security Model](https://docs.wal.app/docs/walrus-memory/fundamentals/architecture/data-flow-security-model.md): Walrus Memory's security model is split between onchain enforcement and offchain operations. Understanding where trust lives helps you make informed decisions about your deployment. - [How Storage Works](https://docs.wal.app/docs/walrus-memory/fundamentals/architecture/how-storage-works.md): When you call memwal.remember(...), the relayer accepts a background job immediately and then stores the memory asynchronously. Here's what happens. The relayer generates a vector embedding from your plaintext content. - [Memory Space](https://docs.wal.app/docs/walrus-memory/fundamentals/concepts/memory-space.md): A memory space is the isolated unit of storage in Walrus Memory. Think of it as a folder or bucket for your memories, you choose which memory space to store into and which to retrieve from. Each user can own as many memory spaces as they want. - [Ownership And Access](https://docs.wal.app/docs/walrus-memory/fundamentals/concepts/ownership-and-access.md): Walrus Memory puts you in full control of your memory. Programmable permissions and explicit ownership define how memory is shared, accessed, and updated, with delegate access for agents and workflows. - [Choose Your Path](https://docs.wal.app/docs/walrus-memory/getting-started/choose-your-path.md): Walrus Memory supports several integration modes depending on how much control you need. Pick the one that fits your use case. > Tip > > These paths aren't mutually exclusive. - [Quick Start](https://docs.wal.app/docs/walrus-memory/getting-started/quick-start.md): The fastest way to get Walrus Memory running is through the TypeScript SDK. - [What Is Walrus Memory](https://docs.wal.app/docs/walrus-memory/getting-started/what-is-walrus-memory.md): > Note > > Walrus Memory is currently in beta and actively evolving. While fully usable today, the team continues to refine the developer experience and operational guidance. the team welcomes feedback from early builders as the team continues to improve the product. - [Walrus Memory](https://docs.wal.app/docs/walrus-memory.md): Walrus Memory gives AI agents persistent, portable memory that works across apps, sessions, and workflows. Ownership and access are enforced onchain through Sui smart contracts, and all content is encrypted through Seal before reaching Walrus. - [Database Sync](https://docs.wal.app/docs/walrus-memory/indexer/database-sync.md): The indexer syncs account data into PostgreSQL so the relayer can resolve ownership quickly without hitting the blockchain on every request. Both the relayer and the indexer connect to the same PostgreSQL instance (with the pgvector extension enabled). Migrations run automatically on boot. - [Onchain Events](https://docs.wal.app/docs/walrus-memory/indexer/onchain-events.md): The indexer listens to Sui events emitted by the Walrus Memory contract and uses them to update local backend state. - [Purpose](https://docs.wal.app/docs/walrus-memory/indexer/purpose.md): The indexer keeps the backend in sync with onchain state so the relayer can resolve accounts quickly. Without the indexer, every authenticated request would require the relayer to scan the onchain AccountRegistry to find which MemWalAccount holds a given delegate key. - [Changelog](https://docs.wal.app/docs/walrus-memory/mcp/changelog.md): Added relayer compatibility metadata checks before opening the MCP bridge. Stdio MCP server for Walrus Memory with browser-based wallet login. Inline memwallogin and memwallogout session tools. Memory tools for remember, recall, analyze, and restore through the Walrus Memory relayer. - [How It Works](https://docs.wal.app/docs/walrus-memory/mcp/how-it-works.md): This page explains what @mysten-incubation/memwal-mcp actually does on the client machine. The package has two main runtime modes. - [Overview](https://docs.wal.app/docs/walrus-memory/mcp/overview.md): Walrus Memory exposes a Model Context Protocol (MCP) server so MCP-aware clients can read from and write to your portable agent memory. - [Quick Start](https://docs.wal.app/docs/walrus-memory/mcp/quick-start.md): This page gets you from zero to a working Walrus Memory MCP server inside Cursor, Claude Desktop, Claude Code, or Codex. - [Reference](https://docs.wal.app/docs/walrus-memory/mcp/reference.md): This page documents every tool, flag, environment variable, and transport route the Walrus Memory MCP package exposes. For a guided walkthrough, start with the Quick Start. - [Changelog](https://docs.wal.app/docs/walrus-memory/openclaw/changelog.md) - [How It Works](https://docs.wal.app/docs/walrus-memory/openclaw/how-it-works.md): The plugin sits between OpenClaw's gateway and the Walrus Memory server. It operates through hooks, automatic callbacks that run on every conversation turn, and optional tools the LLM can call explicitly. - [Overview](https://docs.wal.app/docs/walrus-memory/openclaw/overview.md): The Walrus Memory plugin adds portable, verifiable agent memory to OpenClaw agents. It works alongside OpenClaw's existing file-based memory, automatically recalling relevant context and capturing new facts in the background, with no user action needed. - [Quick Start](https://docs.wal.app/docs/walrus-memory/openclaw/quick-start.md): Get the plugin running and test the memory loop in a few minutes. [x] OpenClaw installed and running You also need a delegate key, account ID, and relayer URL from Walrus Memory, the steps below guides you through getting these. - [Reference](https://docs.wal.app/docs/walrus-memory/openclaw/reference.md): Complete reference for every plugin capability. Hooks are the primary mechanism, they run automatically on every conversation turn without any configuration beyond enabling the plugin. - [API Reference](https://docs.wal.app/docs/walrus-memory/python-sdk/api-reference.md): See also: Configuration Relayer API MemWalSync.create(...) has the same signature and returns a synchronous wrapper. - [Changelog](https://docs.wal.app/docs/walrus-memory/python-sdk/changelog.md): Track what's new, changed, and fixed in memwal (Python). For the latest version, see the PyPI project page. - [Colab](https://docs.wal.app/docs/walrus-memory/python-sdk/colab.md): Use the runnable Walrus Memory Python SDK Colab when you want a notebook-first walkthrough. - [Quick Start](https://docs.wal.app/docs/walrus-memory/python-sdk/quick-start.md): The Walrus Memory Python SDK (memwal on PyPI) gives your agents portable memory that works across apps, sessions, and workflows. Store, recall, and analyze context, fully under your control. It mirrors the TypeScript MemWal client: same relayer, same Ed25519 auth, same methods. - [1. Fire and forget the wait — poll later if you need the blobid](https://docs.wal.app/docs/walrus-memory/python-sdk/usage.md): The Python SDK exposes one relayer-backed client in two forms, plus middleware: | Entry point | Import | When to use | | --- | --- | --- | | MemWal | from memwal import MemWal | Recommended default, async-native; relayer handles embeddings, Seal, and storage | | MemWalSync | from memwal import MemWalSync | Same API surface, synchronous, scripts, notebooks, non-async apps | | withmemwallangchain / withmemwalopenai | from memwal import ... - [Memwal Manual](https://docs.wal.app/docs/walrus-memory/python-sdk/usage/memwal-manual.md): > Note > > Unlike the TypeScript SDK there is no separate MemWalManual class in Python. The Python SDK is relayer-backed: the relayer always handles embedding, Seal encryption, and Walrus storage. - [Memwal](https://docs.wal.app/docs/walrus-memory/python-sdk/usage/memwal.md): The recommended default client. The relayer handles embeddings, Seal encryption, Walrus upload, and vector indexing. The SDK only signs requests and sends text. - [With Memwal](https://docs.wal.app/docs/walrus-memory/python-sdk/usage/with-memwal.md): withmemwallangchain and withmemwalopenai wrap an existing LLM client with automatic memory management. Before each call relevant memories are recalled and injected; after each call the user message is analyzed for new facts (fire-and-forget). - [Configuration](https://docs.wal.app/docs/walrus-memory/reference/configuration.md): Use this page to pick the right config shape quickly. Used by: MemWal.create(config) withMemWal(model, options) | Field | Required | Notes | | --- | --- | --- | | key | yes | Delegate private key in hex | | accountId | yes | MemWalAccount object ID on Sui | | serverUrl | no | Relayer URL. - [Environment Variables](https://docs.wal.app/docs/walrus-memory/reference/environment-variables.md): Use this page when you run your own relayer. For setup steps and deployment context, see Self-Hosting. Environment variables documented here are public relayer contract items. Renaming, removing, or changing their meaning follows the deprecation process in Versioning and Compatibility. - [API Reference](https://docs.wal.app/docs/walrus-memory/relayer/api-reference.md): The Rust relayer exposes these routes. Routes are defined in services/server/src/main.rs. See also: Environment Variables Configuration Versioning and Compatibility All /api/ routes require signed headers. The SDK handles this automatically. - [Benchmark CI Setup](https://docs.wal.app/docs/walrus-memory/relayer/benchmark-ci-setup.md): This document records how to configure the relayer benchmark workflows. The live benchmark intentionally runs only the public relayer /api/recall path. - [Nautilus Tee](https://docs.wal.app/docs/walrus-memory/relayer/nautilus-tee.md): Run the Walrus Memory relayer with a TEE deployment pattern when you want the default SDK flow without giving the host operator direct access to plaintext memory payloads. - [Observability](https://docs.wal.app/docs/walrus-memory/relayer/observability.md): Production relayers should emit structured logs, scrape Prometheus metrics, and send alerts for the external systems Walrus Memory depends on: PostgreSQL, Redis, Sui RPC, OpenAI-compatible embedding/LLM APIs, Seal, Walrus, and the TypeScript sidecar. Every relayer request gets an x-request-id. - [Overview](https://docs.wal.app/docs/walrus-memory/relayer/overview.md): The relayer is the backend that turns SDK calls into memory operations. Using a delegate key signed by the client, it handles the critical workflows, embedding, encryption, storage, and search, on behalf of the user. - [Public Relayer](https://docs.wal.app/docs/walrus-memory/relayer/public-relayer.md): A managed relayer is a simpler experience for teams that want to get started without running infrastructure. If a managed relayer endpoint is available for your environment, it gives you the fastest path to integration. - [Self Hosting](https://docs.wal.app/docs/walrus-memory/relayer/self-hosting.md): Self-hosting means running your own relayer, either pointing at an existing Walrus Memory package ID or deploying an entirely new Walrus Memory instance with your own contract, database, and server wallet. The managed relayer provided by Walrus Foundation is a reference implementation. - [Versioning And Compatibility](https://docs.wal.app/docs/walrus-memory/relayer/versioning-and-compatibility.md): The Walrus Memory relayer is the public protocol/API layer for SDKs, MCP clients, and self-hosted deployments. Treat every route, signed header, response field, runtime config field, and documented environment variable on this page as a versioned contract. - [Advanced Usage](https://docs.wal.app/docs/walrus-memory/sdk/advanced-usage.md): you already have a vector or encrypted payload you want fact extraction with analyze you want memory inside an AI SDK pipeline Use: rememberManual when you already have encrypted payload plus vector recallManual when you already have a query vector Use analyze when you want the relayer to extract facts from longer text and store them as memories. - [Ai Integration](https://docs.wal.app/docs/walrus-memory/sdk/ai-integration.md): Walrus Memory includes an AI SDK integration for applications that already use model middleware. - [API Reference](https://docs.wal.app/docs/walrus-memory/sdk/api-reference.md): See also: Configuration Relayer API Config: | Property | Type | Required | Default | Notes | | --- | --- | --- | --- | --- | | key | string | Yes | | Ed25519 delegate private key in hex | | accountId | string | Yes | | MemWalAccount object ID on Sui | | serverUrl | string | No | | Relayer URL | | namespace | string | No | "default" | Default namespace for memory isolation | For the full config surface, see Configuration. - [Changelog](https://docs.wal.app/docs/walrus-memory/sdk/changelog.md): Added RecallParams for object-style recall(...) calls. Marked the positional recall(...) overload as deprecated in favor of . Documented restore response fields, default limit, pagination behavior, and performance expectations. Added relayer compatibility metadata checks before protected requests. - [Example Map](https://docs.wal.app/docs/walrus-memory/sdk/example-map.md) - [Examples](https://docs.wal.app/docs/walrus-memory/sdk/examples.md): The shortest working Walrus Memory example using the default relayer-backed SDK. - [Overview](https://docs.wal.app/docs/walrus-memory/sdk/overview.md): Walrus Memory exposes SDK surfaces for TypeScript and Python. The SDKs give your agents portable memory that works across apps, sessions, and workflows, fully under your control. Use this first. - [Quick Start](https://docs.wal.app/docs/walrus-memory/sdk/quick-start.md): The Walrus Memory SDK gives your agents portable memory that works across apps, sessions, and workflows. Store, recall, and analyze context, fully under your control. - [Research App Example](https://docs.wal.app/docs/walrus-memory/sdk/research-app-example.md): you want to store structured research findings you want to recall them in later sessions save a structured summary with remember generate targeted queries later use recall to pull relevant findings back into context Structured summaries usually recall better than raw transcripts because they keep the signal high. - [Usage](https://docs.wal.app/docs/walrus-memory/sdk/usage.md) - [Memwal Manual](https://docs.wal.app/docs/walrus-memory/sdk/usage/memwal-manual.md): Use when the client must handle embedding calls and local Seal operations. The relayer still handles upload relay, vector registration, search, and restore. This is the recommended path for Web3-native users who want to minimize trust in the relayer, it never sees your plaintext data. - [Memwal](https://docs.wal.app/docs/walrus-memory/sdk/usage/memwal.md): The recommended default client. The relayer handles embeddings, Seal encryption, Walrus upload, and vector indexing. - [With Memwal](https://docs.wal.app/docs/walrus-memory/sdk/usage/with-memwal.md): Drop-in memory middleware for Vercel AI SDK apps. - [Unsigned Health Check Rationale](https://docs.wal.app/docs/walrus-memory/security/health-check-unsigned.md): GET /health and GET /version The health and version endpoints are intentionally left unauthenticated and unsigned. They do not require a valid Ed25519 signature in headers like the rest of the API. ## Optional ### Tusky Migration Guide - [Tusky Migration Guide](https://docs.wal.app/docs/tusky-migration-guide.md): As of December 19, 2025, the storage service Tusky is shutting down. Data stored on Walrus through Tusky is still safe and accessible. During Tusky's sunsetting period, you can continue reading your data, however you must either migrate to using Walrus directly or through alternative tooling. ### Legal - [Privacy](https://docs.wal.app/docs/legal/privacy.md): Last Updated: February 10, 2024 This Privacy Policy is designed to help you understand how Walrus Foundation (collectively called the “Organization", "we," "us," and "our") collects, uses, and shares your personal information and to help you understand and exercise your privacy rights in accordance with applicable law. - [Testnet TOS](https://docs.wal.app/docs/legal/testnet_tos.md): Last updated: March 26, 2025 By using Walrus Testnet software, technologies, tools, and other services (collectively “Testnet”) offered by Walrus Foundation ("Walrus Foundation", "we", "our"), you agree to the general Walrus Terms of Service and these additional Testnet Terms of Service (together, the “Terms”). - [Walrus General TOS](https://docs.wal.app/docs/legal/walrus_general_tos.md): Please read these Terms of Service (the “Terms”) and our Privacy Policy carefully because they govern your use of the website, the user interface, and other offerings located at walrus.xyz, (the “Site”) offered by Walrus Foundation (“Walrus Foundation,” “we,” “our”).