Skip to main content

Hosting a Website on Swarm and Linking it to ENS

This guide explains how to host a static website on Bee using swarm-cli and make it accessible through Ethereum Name Service (ENS).

Part one covers uploading and accessing your site through the raw Swarm hash.

Part two shows how to register your Swarm hash with your ENS domain so it can be easily accessed by anyone through public ENS gateways like eth.limo, bzz.link, or localhost on a Bee node.

Part three shows how to upload your website through a feed and register the feed manifest with ENS in order to provide a static hash for the website. This means you no longer need to update your ENS record every time you make a change to your website, and is the recommended method for hosting a publicly accessible website on Swarm.

1. Hosting and Accessing Your Website on Swarm​

Prerequisites​

You can download the example website files from the ethersphere/examples repository.

Uploading the Website​

  1. Go to the folder containing your website files.

The example website files look like this:

my-website/
├── index.html       # main landing page
├── 404.html         # custom error page
├── styles.css       # basic styling
├── script.js        # optional script
├── favicon.svg      # site icon
└── robots.txt       # default robots config
  • index.html will be served by default when users visit the root URL.
  • 404.html will be served for non-existent paths.
  • The other files are optional and can be customized.
  1. Run:
swarm-cli upload . `
  --stamp 3d98a22f522377ae9cc2aa3bca7f352fb0ed6b16bad73f0246b0a5c155f367bc `
  --index-document index.html `
  --error-document index.html
  • Replace <BATCH_ID> with your postage batch ID.
  • --index-document tells Bee which file to serve at the root.
  • --error-document defines the fallback file for missing paths.
  1. The upload will return a Swarm reference hash, for example:
cf50756e6115445fd283691673fa4ad2204849558a6f3b3f4e632440f1c3ab7c

Copy this and save it. You’ll need it for both direct access and ENS integration.

Accessing the Website​

Anyone with a Bee node can now access the site using the Swarm hash you just saved:

http://localhost:1633/bzz/<swarm-hash>/

2. Connecting Your Website to ENS​

Once the site is uploaded, you can make it accessible via an easy to remember ENS domain name:

https://yourname.eth.limo/
https://yourname.bzz.link/

or through your own node:

http://localhost:1633/bzz/yourname.eth/
tip

If the site doesn’t load from localhost, it’s probably an with the resolver RPC (the RPC endpoint for the Ethereum node used to resolve your ENS domain name).

Some endpoints, such as:

https://cloudflare-eth.com

may not resolve properly on localhost.

As of the writing of this guide, both of these free and public endpoints work reliably for localhost resolution:

https://mainnet.infura.io/v3/<infura-api-key>
https://eth-mainnet.public.blastapi.io

Alternatively, you can run your own Ethereum node and use that as the RPC.

Using the Official ENS Guide​

The ENS team provides a clear walkthrough with screenshots showing how to add a content hash to your domain with their easy to use app:

How to add a Decentralized website to an ENS name

The guide covers:

  • Opening your ENS domain in the ENS Manager
  • Navigating to the Records tab
  • Adding a Content Hash
  • Confirming the transaction

Swarm-Specific Step​

When you reach Step 2 in the ENS guide (“Add content hash record”), enter your Swarm reference in the following format:

bzz://<swarm-hash>

Example:

bzz://cf50756e6115445fd283691673fa4ad2204849558a6f3b3f4e632440f1c3ab7c

This works across:

  • eth.limo and bzz.link
  • localhost (with a compatible RPC)
  • any ENS-compatible Swarm resolver

You do not need to encode the hash or use any additional tools. bzz://<hash> is sufficient.

If you plan to update your website in the future, you should publish your website hash to a feed rather than pointing ENS directly to the raw content hash.

Why:

  • ENS only needs to be set once
  • You can push new website versions later
  • Your ENS name always resolves to the latest upload

In this section, you will:

  1. Create a publisher identity
  2. Upload your site to a feed (this automatically creates the feed manifest)
  3. Copy the feed manifest reference
  4. Use that manifest reference as your ENS contenthash

This ensures future website updates require no ENS changes.

Prerequisite: Have your initial site hash​

From Part One you should already have uploaded your site and seen something like:

Reference: 1c686dee5891aae4ea97db397165ce511efdfc40b64846ac6f00f7330a0ed65f

We will refer to this as <site-hash> in the examples below.

In the next step we will re-upload the site using a feed so that ENS can always track updates.

Step 1: Create a dedicated publisher identity​

This key will sign feed updates.

swarm-cli identity create website-publisher

Record the output — you will need this identity for future updates.

If you need to view/export it later:

swarm-cli identity export website-publisher

Step 2: Upload your website to a feed (creates the manifest automatically)​

swarm-cli feed upload ./website \
  --identity website-publisher \
  --topic-string website \
  --stamp <postage-batch-id> \
  --index-document index.html \
  --error-document 404.html

You will see output that includes your feed manifest reference, for example:

Swarm hash: 387dc3cf98419dcb20c68b284373bf7d9e8dcb27daadb67e1e6b6e0f17017f1f
URL: http://localhost:1633/bzz/387dc3cf98419dcb20c68b284373bf7d9e8dcb27daadb67e1e6b6e0f17017f1f/
Feed Manifest URL: http://localhost:1633/bzz/6c30ef2254ac15658959cb18dd123bcce7c16d06fa7d0d4550a1ee87b0a846a2/
Stamp ID: 3d98a22f
Usage: 50%
Capacity (mutable): 20.445 KB remaining out of 40.890 KB

You can find the manifest hash at Feed Manifest URL in the URL right after /bzz/: 6c30ef2254ac15658959cb18dd123bcce7c16d06fa7d0d4550a1ee87b0a846a2

Save this hash, you will use it for the next step.

This is your permanent website reference. It is a reference to a feed manifest which points to the latest feed entry so that you can use it as a static, unchanging reference for your website even as you make multiple updates to the site. Every time you update the website through the feed, this manifest will point to the hash for the newest version of the website.

Step 3: Use the feed reference as the ENS contenthash​

Follow the same official ENS guide for registering a content hash adding your content hash in the ENS UI (see Section 2). However, this time, rather than registering your website's hash directly, register the feed manifest hash we saved from the previous step (6c30ef2254ac15658959cb18dd123bcce7c16d06fa7d0d4550a1ee87b0a846a2 from our example above).

Example:

bzz://6c30ef2254ac15658959cb18dd123bcce7c16d06fa7d0d4550a1ee87b0a846a2

Now your ENS name will always point to a static reference which will always resolve to the latest version of your website.

Updating your site in the future​

When you have a new version of your site, just run feed upload again against the same topic and identity:

swarm-cli feed upload ./website \
  --identity website-publisher \
  --topic-string website \
  --stamp <postage-batch-id> \
  --index-document index.html \
  --error-document 404.html
  • The feed manifest reference stays the same.
  • The feed now points to the newly uploaded site version.
  • No ENS changes needed.
tip

It may take a few minutes for caches to reload and make your changes accessible, especially with ENS gateway services like eth.limo and bzz.link.