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.

Already have a project and want to start straight away? This is your starting point — work down from here. Taking the bootcamp instead? The recorded online session walks through the setup sections with you, so you don't need to read ahead. Keep this as your reference for the rest of the hackathon.

Written so you can hand it to a coding agent and not have to learn the vocabulary yourself. If you already know this stack, skip to Manual path.

What Swarm can do

Plain English first; the italic line under each is the same thing in infrastructure vocabulary. Read whichever one helps.

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". The data is invisible rather than locked. ACT: grantee lists keyed to Ethereum public keys; unauthorized reads 404.

What revocation does and doesn't do. Removing someone cuts them off from current and future updates. It does not reach backwards: anything already downloaded is theirs to keep, and historical versions they were granted can still be reached at the timestamp they were granted at. Design for "cut off from here on", not for "unsend".

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 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 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. The receiving or service node must be a full node.

Treat these as notification channels, not a mailbox. If you need a durable inbox — something that reliably holds messages for someone who's away — store the payload and use a feed as the pointer, with PSS or GSOC as the nudge. That's the pattern Swarm Mail uses, and it's the one that survives contact with a light node.

Hand data back to the person it's about. Readable by whichever tool they permit, including one you didn't write. Encrypted user-owned state, portable across apps.

Where it's genuinely a bad fit. Anything needing sub-second random writes, a queryable database, or storage you never think about again. Space is prepaid and expires, so "upload once and forget for a decade" is not the shape of this tool.

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 remove a sender's access to everything from here on. Work-in-progress that stops updating when an engagement ends. Records that follow a person between clinics or caseworkers, where the person holds the access list rather than the institution.

The clearest live demo: grant someone access, publish an update they can read, revoke them, publish another they can't. It shows real control without pretending you can unsend.

Things you want kept on your own terms. An archive whose continued existence depends on you renewing storage rather than on a platform's terms of service: a station's recordings, a folded publication, a neighborhood's photographs. Evidence with an address proving it wasn't edited — claims, damage reports, disclosure timelines. A dataset anyone citing it can verify they're reading unchanged.

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 of what you keep. A group's messages with no operator in the middle. A site that outlives whoever built it, as long as someone keeps the space paid.

Or something we haven't thought of. Genuinely — bring it to the booth. That conversation is worth more to us than a submission.

The fast path: the agent skills

Swarm Foundation maintains a set of agent skills covering setup, uploads, updateable addresses, access control, publishing, messaging, and troubleshooting — so your agent follows current, correct steps instead of whatever it half-remembers about a network it saw once in training.

Prerequisites: Claude Code, Node.js 18+.

git clone https://github.com/ethersphere/swarm-quickstart-skills.git
cp -r swarm-quickstart-skills/.claude/ /path/to/your-project/
cd /path/to/your-project && claude

Then type:

/swarm

It checks what you have, and routes you to the right next step — installing a node, funding it, buying storage, uploading, or scaffolding an app. This is the path the recorded online session follows.

What the skills are and aren't for. They take the repetitive parts — installation, version checks, the same four troubleshooting steps everyone hits — so your time goes on design decisions instead. They're not a substitute for understanding your node: when something breaks at the booth, the useful conversation is about architecture, and that needs you to know what the thing is doing.

Docs: https://docs.swarm.bzz.link/docs/develop/tools-and-features/ai-agent-skills/ Repo: https://github.com/ethersphere/swarm-quickstart-skills

Working programmatically instead? There's also a swarm-mcp MCP server — ask at the booth.

If you use a different agent

Paste this. It's self-contained.

I'm going to a hackathon where I'll store data on Swarm, a decentralized
storage network. Get my laptop ready. Pick sensible defaults rather than
asking me to decide things I haven't learned yet, and tell me what you did.

1. Check for Node.js 18+ and curl. Install if missing.
2. Get the latest Bee release tag:
   curl -s https://api.github.com/repos/ethersphere/bee/releases/latest | jq -r .tag_name
3. Install Bee with that tag:
   curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=<TAG> sudo bash
   Verify: bee version
4. Install the CLI: npm install -g @ethersphere/swarm-cli
5. Start Bee in ultra-light mode — no funding needed, downloads work immediately:
     bee start --password <make one up and tell me> --api-addr 127.0.0.1:1633
   It may return 503 for the first 10-30 seconds. Normal.
6. Confirm: swarm-cli status
7. Download something public from Swarm to prove the connection works.
8. Stop there. I'll get a gift code from Swarm to enable uploads.

Reference: https://docs.swarm.bzz.link/docs/bee/installation/quick-start

Your gift code

A gift code is a private key holding a small amount of xBZZ and xDAI on Gnosis Chain — enough to fund your node and buy your first storage. The recorded online session shows you how to redeem one, or pick one up at the booth in Amsterdam. With the agent skills, /swarm handles the rest. Otherwise:

I have a Swarm gift code. Use it to enable uploads from my node.

1. Redeem it to my running node's wallet:
     swarm-cli utility redeem <CODE> --json-rpc-url https://xdai.fairdatasociety.org
   If it rate-limits (429), try --json-rpc-url https://rpc.gnosischain.com
2. Stop the node, restart as a light node so it can pay for uploads:
     bee start --password <same as before> --swap-enable \
       --api-addr 127.0.0.1:1633 \
       --blockchain-rpc-endpoint https://xdai.fairdatasociety.org
   It deploys a chequebook and syncs chain data — around 5 minutes.
3. Watch swarm-cli status until the chain-sync gap is under ~10 blocks.
4. Buy prepaid storage (a "postage stamp"). Compute the amount from the LIVE
   price, don't hardcode it:
     PRICE=$(curl -s http://localhost:1633/chainstate | jq .currentPrice)
     # amount = PRICE * 17280 blocks/day * days wanted
   A gift code holds roughly 0.5 xBZZ, which covers about depth 17 (~40 KB,
   ~1 week). Do NOT try depth 22 — it needs ~4 xBZZ and will fail.
     swarm-cli stamp buy --depth 17 --amount <computed>
   Save the stamp ID. Wait 2-3 minutes before using it.
5. Prove it end to end:
     echo "Hello Swarm" | swarm-cli upload --stdin --stamp <ID> --name hello.txt
     swarm-cli download <RETURNED_HASH>
6. Tell me the hash and where the file landed.

This funding step is historically where people gave up on Swarm. It's now about four minutes of an agent's time, and we're standing right there.

Storage is rented, not bought once. A stamp covers a set amount of data for a set period, and when it runs down the data stops being served. Top it up (swarm-cli stamp topup --stamp <ID> --amount <more>) and it stays available. Worth designing for now rather than discovering in November: a hackathon-sized stamp lasts about a week, so if you want your demo alive for a judge, an investor, or your own portfolio, plan on extending it. Check what you have with swarm-cli stamp list — the TTL is in there.

Building your thing

Describe what you want in plain language. Something like:

I want to build <describe it plainly>, storing the data on Swarm.
My node runs at http://localhost:1633 and I have a stamp ID.

Use the JavaScript SDK: npm install @ethersphere/bee-js
Check whether create-swarm-app fits what I'm making and use it if so.

Ask me which of these I need before choosing:
- Encrypted, readable only by specific people, revocable later
  → access control (ACT): https://docs.swarm.bzz.link/docs/develop/act
  → grantees are Ethereum public keys. Save the "history reference" it returns
    somewhere safe — losing it means permanently losing access to the data.
  → IMPORTANT: revocation cuts off current and future updates only. It cannot
    retract an already-downloaded file, and a former grantee can still reach
    historical versions at the timestamp they were granted. Don't design a
    feature that promises to unsend something.
- One stable address I can update later → a feed
- A website or app frontend → upload the built folder, optionally point an ENS
  name at it and serve via eth.limo or bzz.link
- Encrypted notifications between people or programs → PSS (point-to-point) or
  GSOC (many-to-one). The receiving/service node must be a FULL node — check my
  node mode before promising this. For a durable inbox that holds messages for
  someone who is away, don't rely on PSS alone: store the payload and use a
  feed as the pointer.

References: https://bee-js.ethswarm.org/docs/ · https://docs.swarm.bzz.link
Start by asking what the app should do. Don't scaffold yet.

Five things agents reliably get wrong

Worth pasting in alongside the above.

1. 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.
2. They hardcode a storage price. It's live — read it from http://localhost:1633/chainstate.
3. They write code for full-node features while you're running a light node. Subscribing to incoming messages is the usual casualty. Have your agent check node mode before it promises you a feature.
4. They build "unsend" on top of ACT. Revocation controls access from now on; it can't retract a downloaded file or seal off historical versions from a former grantee. If your agent describes revocation as making data disappear for someone, correct it.
5. The SDK reports the newest Bee release as an "unsupported version". Stale version string, not a real problem. Ignore it.

Stuck for more than fifteen minutes? Walk to the booth. Nobody is impressed by suffering.

Manual path

For anyone who'd rather read than delegate.

Node modes, since this trips people up:

A light node covers everything in the sessions. Some messaging features need a full node.

Don't want to run anything?

If your app needs sign-in and uploads without asking your users to think about any of this, Swarm ID by Snaha gives you passkey or Ethereum sign-in, app-provided storage, encrypted uploads, and multi-device sync.

npm install @snaha/swarm-id · docs · demo

Real apps to read

Projects built during a past Swarm Accelerator round — the program isn't running any more, but the repos are still 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: the Swarm booth at De Hallen, or Discord.