This page lives on Swarm, behind a feed. The address never changes; the content behind it does. Bookmark it — we update it as details firm up.
🐝 Swarm technical guide — Common S3nse 2026
Companion to the builder brief.
This guide starts where the bootcamp ends. It assumes you have postage stamps in hand. Don't have one yet? The tutorial slides walk you through install, funding, and your first stamp, step by step.
Nothing here costs you money. Every step that needs xBZZ or xDAI is covered by a gift code. Don't buy tokens — come find us, @yjkellyjoo.
Don't want to run a node at all? Beeport buys a stamp and uploads from the browser, on someone else's node. Read anything back through a public gateway — https://gateway.ethswarm.org/bzz/<hash>/. You can move to your own node later.
Every link, command and SDK lives on the cheatsheet. Two pages, print-ready, paper copies at the booth.
What Swarm can do
Plain English, with the infrastructure term in italics under each.
Control who can read something, and change your mind later. You set read permission per person and update the list whenever you like. Someone with no grant doesn't get a permission error — they get "not found". ACT: grantee lists keyed to Ethereum public keys; unauthorized reads 404.
Prove a file hasn't changed since you shared it. The address is derived from the contents, so if a link resolves, what's behind it is byte-identical to what you published. Content addressing — the reference is a hash of the data.
Publish without a server to maintain. A static site, an archive, a gallery. Nothing to patch, no uptime to babysit; you keep the storage topped up instead of paying a host. Static upload behind an ENS name, served via eth.limo, bzz.link, or any Swarm node.
Keep one address that always resolves to your newest version. Publish an update, the address stays the same, people bookmark it once. Feeds — owner plus topic, through a manifest for a stable URL.
Send encrypted messages with no server in the middle. Point-to-point, or many-to-one for rooms and notifications. No operator holding the log. PSS point-to-point, optionally encrypted; GSOC many-to-one. Both require a full Bee node.
Working with your stamps
The slides explain what depth and amount are. This is what using them looks like.
Verify your stamp's status.
swarm-cli stamp list # all of them, with usage %
swarm-cli stamp show <ID> # one, in detail
Two numbers decide whether your demo survives Saturday:
| What it means | What it looks like when it goes wrong | |
|---|---|---|
| Usage % | How full the batch is | Uploads start failing once it's full. Nothing already stored is lost |
| TTL | Seconds of paid time left | It hits zero and the network is free to drop everything the batch covered |
A gift-code stamp is sized for a demo, not a media library.
When it fills up, or runs down. One command handles both:
swarm-cli stamp extend
The explicit versions:
swarm-cli stamp topup --stamp <ID> --amount <more> # more time
swarm-cli stamp dilute --stamp <ID> --depth <bigger> # more space
Diluting costs you time. The amount you already paid now has to cover more space, so the TTL falls as the depth rises. Top up after you dilute, not before.
A new stamp isn't usable the moment you buy it. The batch takes a couple of minutes to go live. In code, wait rather than sleep:
await bee.stamp.waitForUsable(stampId)
Out of xBZZ to extend with? Don't go buy any. Come find us — @yjkellyjoo.
Putting real data on it
Files and folders
upload takes either. A directory gives you one hash for the whole collection.
swarm-cli upload ./report.pdf --stamp <ID>
swarm-cli upload ./my-folder --stamp <ID>
swarm-cli download <HASH>
Flags worth knowing:
| Flag | Why |
|---|---|
--encrypt |
Encrypts before upload. The key rides in the reference, so anyone with the hash can read and nobody else can |
--sync |
Waits for chunks to propagate. Use it before a demo — the default returns as soon as your node has the data |
--pin |
Keeps a copy on your own node so retrieval doesn't depend on the network having it |
--qr |
Prints a scannable URL. Good for getting a demo onto a phone |
A website or app frontend
Upload the built folder and name the entry point.
swarm-cli upload ./dist \
--stamp <ID> \
--index-document index.html \
--error-document index.html
--error-document index.html is what makes client-side routing work — any unknown path falls back to your SPA instead of 404ing.
Open it at:
https://gateway.ethswarm.org/bzz/<HASH>/,- on your own node at
http://localhost:1633/bzz/<HASH>/, - or with an ENS name at
https://<ENS-NAME>.bzz.link.
Learn how to do this in detail at https://justdeploy.bzz.link.
From inside your app
npm install @ethersphere/bee-js
import { Bee } from '@ethersphere/bee-js'
const bee = new Bee('http://localhost:1633')
// a file — returns { reference, historyAddress }
const { reference } = await bee.file.upload(STAMP_ID, data, 'hello.txt')
// a built directory
const site = await bee.collection.uploadFromDirectory(STAMP_ID, './dist')
// back again
const file = await bee.file.download(reference)
bee.data.upload() / bee.data.download() are the raw-bytes equivalents when you don't need a filename.
Starting from nothing? npm init swarm-app scaffolds a project with Swarm already wired up.
Going further
Feeds — one address, changing content
A hash changes when the bytes change, breaking every link you've shared. A feed is an address derived from you plus a topic, and always resolves to your latest update.
swarm-cli identity create demo
swarm-cli feed upload ./dist --identity demo --stamp <ID> --topic-string my-app
swarm-cli feed print --identity demo --topic-string my-app
In an app: bee.feed.makeWriter(topic, signer) to publish, bee.feed.makeReader(topic, owner) to follow, and bee.feed.createManifest() once for a permanent URL.
A feed slot holds 4 KB. Store the payload as a normal upload and write the reference into the feed. Writes are append-only per index, so resolve the current index before writing.
📖 https://docs.swarm.bzz.link/docs/develop/dynamic-content
ACT — encrypted, revocable sharing
Upload encrypted, then grant read access per Ethereum public key. Revoke and they lose access to new versions.
swarm-cli access init --stamp <ID> --list-name team -g 0x<PUBLIC_KEY>
swarm-cli upload ./report.pdf --stamp <ID> --share-with team
swarm-cli access grant --list-name team -g 0x<PUBLIC_KEY>
swarm-cli access revoke --list-name team -g 0x<PUBLIC_KEY>
In bee-js: bee.grantee.create(), .patch(), .get().
Save the history address. Every ACT upload returns one alongside the reference — historyAddress on the result. Lose it and you permanently lose access to your own data.
Revocation cuts off future access, not past. Anything already downloaded is theirs, and historical versions stay reachable at the timestamp they were granted. Design for "cut off from here on", never "unsend".
The clearest live demo there is: grant someone access, publish an update they can read, revoke them, publish another they can't.
📖 https://docs.swarm.bzz.link/docs/develop/act
A name people can type
Point an ENS name's content hash at your feed manifest and it resolves on bzz.link and eth.limo. Do it once against a feed and the record never needs touching again.
📖 https://docs.swarm.bzz.link/docs/develop/host-your-website
Messaging — PSS and GSOC
Point-to-point (PSS) or many-to-one (GSOC), with no operator holding the log.
Both need a full node. The gift code sets you up with a light node, and no flag changes that — it's disk and uptime, not funding. Check your node mode before designing around messaging.
They're notification channels, not a mailbox. For a durable inbox, store the payload and use a feed as the pointer, with PSS or GSOC as the nudge.
📖 https://docs.swarm.bzz.link/docs/develop/tools-and-features/gsoc
Project ideas
Prompts, not requirements. One thing working properly beats five half-built.
Things you hand over, and can cut off. An intake box where you can revoke a sender's access. Work-in-progress that stops updating when an engagement ends. Records that follow a person between clinics, where the person holds the access list, not the institution.
Things you want kept on your own terms. An archive that survives on your renewals rather than a platform's terms of service — a station's recordings, a folded publication. Evidence with an address proving it wasn't edited. A dataset anyone citing it can verify.
Things that should belong to the person, not the app. An assistant's memory that survives switching assistants. Backups with no company holding an index. A group's messages with no operator in the middle.
Or something we haven't thought of. Bring it to the booth — that conversation is worth more to us than a submission.
An agent as a companion
Useful for the repetitive parts. Not a substitute for knowing what your node is doing.
git clone https://github.com/ethersphere/swarm-quickstart-skills.git
cp -r swarm-quickstart-skills/.claude/ /path/to/your-project/
/swarm checks what you have and routes you. /swarm-stamps, /swarm-upload-download, /swarm-host-website, /swarm-act and /swarm-feed go straight to one topic; /swarm-troubleshoot when a command fails. They follow the current docs rather than training data.
Five things agents reliably get wrong:
- They buy far more storage than a hackathon needs, then fail because the gift code can't cover it. Depth 17 is fine for a demo.
- They hardcode a storage price. It's live — read it from
http://localhost:1633/chainstate. - They write full-node code while you're on a light node. Message subscriptions are the usual casualty.
- They build "unsend" on top of ACT. Revocation controls access from now on; it can't retract a downloaded file.
- The SDK reports the newest Bee release as an "unsupported version". Stale version string. Ignore it.
Stuck for more than fifteen minutes? Walk to the booth. Nobody is impressed by suffering.
Real apps to read
Built during a past Swarm Accelerator round — the best source for how people structure real apps on Swarm:
- Swarm Mail — encrypted mailboxes that work when the recipient is offline
- Swarm Meet — peer-to-peer video calls, metadata on Swarm
- Swarm Collab — collaborative editor keeping every version
- Swarm MCP App — file and storage management inside AI chats
Questions, or out of funds: the Swarm booth at De Hallen, or #hackathon on Discord / Telegram — tag @yjkellyjoo.