SWARM WORKSHOP · 01
How to run a Bee node
Install it, fund it, store something, get it back.
01/35
Presenter note
Name, role, one sentence on Swarm Foundation. Then go straight into what Swarm is — don't preface it with an agenda.
WHAT SWARM IS
Swarm is a peer-to-peer network of Bee nodes.
They collectively provide censorship-resistant decentralized storage and communication services.
“Swarm's mission is to enable a self-sovereign global society and permissionless open markets by providing scalable decentralized storage infrastructure for Web3.”
02/35
Presenter note
Both lines are the documentation's own words — worth using verbatim so the vocabulary here matches the vocabulary they'll read later. Assume the reader arrived from a link and knows nothing; this is the slide that earns the right to say “node” on the next one.
WHAT A NODE IS
A Bee node is your way in — not a server you maintain.*
*For ultra-light and light. A full node also stores and serves data for the network, which makes it a server in a sense.
03/35
Presenter note
Kills the most common first question — “am I now running infrastructure?” No. Let the picture do the work; don't narrate the boxes.
WHERE THE MONEY GOES
You rent space from the network. The rent goes to the nodes.
~55 xBZZ stores ~630 MB for a year, around $2.50 at today's rate*.
Gas is separate and small: under 0.01 xDAI a transaction.
*The storage price and the exchange rate move. Read the live price before you buy rather than trusting a figure on this slide.
04/35
Presenter note
This is why there's a funding step later, so answer it before they hit it. The point that lands: nobody is invoicing them — the stamp money is redistributed to the nodes doing the storing, and the gas is Gnosis Chain's, not Swarm's. Don't get drawn into the redistribution lottery or staking here; both come later and neither matters for a light node.
WHAT YOU LEAVE WITH
By the end of this you'll have
a node of your own,
storage you've paid for, and a
file you can prove you stored.
No prior Swarm experience assumed.
05/35
Presenter note
Deliberately plain words — “postage batch” hasn't been defined yet and shouldn't be used here. Say it, then stop talking for a beat. This is the contract for everything that follows.
HOW TO USE THIS MATERIAL
Work through it at your pace.
| From here | What you have at the end of it |
|---|---|
| Install | bee and swarm-cli on your machine |
| First download | A running node — no funding yet |
| Funding | xDAI and xBZZ in your node's wallet |
| How it works | Batches, depth, amount — while it syncs |
| Buy and upload | A batch, and a file on Swarm |
| What breaks | The five expensive mistakes |
Every command is on this page. Stuck? discord.ethswarm.org
06/35
Presenter note
This slide replaces what a live session gets for free: navigation, permission to fall behind, and somewhere to go when it breaks. Say the help channel out loud — people skim slides but they hear sentences.
NODE MODESreference
Three node modes.
You will run a Light node.
| Mode | What it costs | What that unlocks |
|---|---|---|
| Ultra-light | Nothing | Read from Swarm directly — no gateway in between, up to a small allowance |
| Light | xDAI & xBZZ | Upload — buy stamps, write your own data |
| Full | Plus disk and uptime | Stores for the network, and earns on bandwidth |
| Full + stake | 10 xBZZ, non-refundable | Joins the redistribution game — optional |
Staking is a separate, optional step. A full node earns on bandwidth without it — only the redistribution game needs a stake, and that stake is non-refundable.
07/35
Presenter note
Reference slide — tell them to bookmark it. Say the plan out loud: we start ultra-light because it needs no funding and it proves the install, then fund it and restart as light. That framing makes the restart later feel deliberate rather than like a false start. The bottom two rows are there to answer “do I have to stake?” — no. A full node earns on bandwidth on its own; the stake only buys into the redistribution game. Don't teach the game here.
PICK YOUR LANEreference
Three ways to run one.
| What you need | What drives it | Best if | |
|---|---|---|---|
| Terminal — demoed | Node.js 18+, a shell | You, copy-pasting this page | You want to see what's actually happening |
| Agent | Node.js 18+, Claude Code | /swarm-setup-bee | You want the tedium handled |
| Desktop app | Just a laptop | A GUI | You don't want a terminal at all |
Windows: WSL2 first for the top two. The desktop app runs on Windows natively.
Switch lanes whenever you like — all three end at a running Bee node.
08/35
Presenter note
We demo the terminal because the whole point of the hour is seeing what a node install actually does — say that out loud, and say the agent lane is coming at the end so nobody on it feels skipped. Name Swarm Desktop so it's findable — ethswarm.org/build/desktop — say it's beta, say it works, and say the CLI is what everything downstream assumes.
INSTALL · STEP 1
Node 18 or newer
node --version && npm --version09/35
Presenter note
Switch to the terminal here and stay there until the sync wait. Run it by hand. Anything older than 18 and Bee's tooling misbehaves in ways that look like network problems — say that, it doesn't need to be on the slide. /swarm-setup-bee checks the same thing first, but they don't get to see what it checked.
INSTALL · STEP 2
Install swarm-cli
npm install --global @ethersphere/swarm-cli10/35
Presenter note
Explain the ordering out loud, it's counterintuitive: the CLI comes first because it can fetch Bee for you. swarm-cli is the thing you'll live in; Bee is the binary it talks to.
INSTALL · STEP 3
Download Bee
swarm-cli quickstartOr the documented installer: curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | bash
11/35
Presenter note
The orange thing on this slide is the command. Say what quickstart does — grabs the right binary for their platform, no sudo — and say why you're not using the curl one-liner: nobody should be trained to paste a piped script reflexively.
INSTALL · STEP 4
Confirm
bee version2.8.2 or newer.
Nothing? Don't grind — switch lanes. Swarm Desktop does the same job with a GUI.
12/35
Presenter note
2.8 was a breaking change, which is why 2.7.x won't do. Say the reassuring line out loud: if it prints a version, they're past the only genuinely fiddly part. If it didn't print, give explicit permission to switch lanes rather than grind — ten minutes lost to an install is ten minutes not spent building.
RUN IT
Start the node
bee start \
--password YOUR_PASSWORD \
--api-addr 127.0.0.1:1633It comes up in ultra-light mode — ready to download.
That password protects your node's keys. One of them is full control of its Gnosis Chain wallet — lose the password and the funds in that wallet are unrecoverable.
13/35
Presenter note
Make up a password and write it down where they can see you do it. Say what it's actually protecting: the docs are blunt that swarm.key “grants full control over your node's Gnosis Chain account” and that if it's lost, you cannot recover funds. Not a trip hazard, a key. Uploads need funding and that's the next section — one sentence of signposting, then move on; this section is about proving the node can read. Security aside worth ten seconds: 127.0.0.1 is deliberate — never expose 1633 to the internet.
RUN IT
A 503 for the first thirty seconds is normal
swarm-cli statusThe node is waking up and finding peers. Wait, retry, don't debug it.
14/35
Presenter note
Show the 503 happening if you can. Seeing the scary thing be fine is worth more than being told it's fine.
RUN IT
Your node can already read Swarm
swarm-cli download cf1df8da8f0a858bd417c34ca26f77fd0ee56351de53db8be3c158b57af811fe/how-to-run-a-nodeThese slides are on Swarm. That's the hash — your brand-new node just fetched the thing you're looking at.
No gateway in the middle. A public gateway would have worked too — but then you'd be depending on whoever runs it.
15/35
Presenter note
The nicest moment in the session — make it land. Publish this page first, so the hash is fixed and verified before anyone runs it. This is where ultra-light earns its place: it's reading the network on its own account rather than through someone else's.
RENTING SPACE
You rent space directly. An amount of storage, for a length of time.
No account. No sign-up. No card.
16/35
Presenter note
This lands better than any technical explanation. Say “rent” and keep saying it — it's the word the rest of the deck uses, and it sets up the “rented, not bought” slide instead of surprising them with it. A tenancy you hold is also one you have to renew.
STAMPS
You buy stamps up front. Everything you upload carries one.
That's what the xBZZ is for.
17/35
Presenter note
Let the picture do it — you buy stamps in advance, and everything you send carries one. The pieces are chunks; don't say the word yet, it's defined later with the hash. Don't teach depth or amount here either — that block is coming while they wait, and doing it twice is how you lose them.
WHAT YOU NEED
Two tokens, both on Gnosis Chain.
| Token | Amount | What it's for |
|---|---|---|
| xDAI | ~0.01 | Gas — enough to get the node started |
| xBZZ | ~0.20 | Your first stamps |
Not Ethereum mainnet. Gnosis Chain.
18/35
Presenter note
Enough to get them funded and moving. Both amounts are the documentation's own — say they're approximate and that the real sizing comes while the node syncs, so nobody stalls here trying to work out what they need. Say the chain twice: it's the one mistake here that loses money.
WHAT YOU NEED
Three routes, easiest first
| Route | Use it when |
|---|---|
| fund.bzz.limo | You hold crypto on any chain — no bridging, no swapping |
| CoW Swap · Jumper · Gnosis Chain bridge | Buying xBZZ directly, or bringing BZZ over from mainnet |
| Gnosis faucet | You only need the xDAI for gas |
swarm-cli addresses # several — fund the Ethereum one19/35
Presenter note
Run swarm-cli addresses and point at the Ethereum one specifically — the command prints several and only that one takes funds. Be straight about the friction: this is where someone with no crypto has to go get some, and there's no way around it for a light node. Anyone who stops here keeps everything from the ultra-light section forever. Worth noting fund.bzz.limo is itself served from Swarm.
UPGRADE TO A LIGHT NODE
Same node. Swap enabled. Now it can pay.
Ctrl+C the node you have running first. Then start it again with the same password.
bee start \
--password YOUR_PASSWORD \
--swap-enable \
--api-addr 127.0.0.1:1633 \
--blockchain-rpc-endpoint https://xdai.fairdatasociety.orgThat RPC is a shared public endpoint and gets rate limited. Use your own Gnosis Chain endpoint if you have one.
20/35
Presenter note
The stop comes first or the restart fails on a port already in use — say it before they start typing. Say why that specific RPC: it's archival, which Bee needs on first start to read batch history, and the docs are explicit that a non-archival endpoint gives you
storage: not found on startup. It's also shared, so if the sync crawls, a private endpoint is the fix.UPGRADE TO A LIGHT NODE
It's deploying a chequebook and reading chain history. About five minutes.
| Deploying a chequebook | Every light and full node gets one automatically. It's how the node pays peers for bandwidth. |
| Reading chain history | Catching up on which batches have paid for what, so it knows which data the network owes you. |
waitYour node is syncing. Read on while it does, or come back when it's done.
21/35
Presenter note
The pivot into the teaching block, and the first pause card. Analogies land here — the chequebook is a bar tab with the peers it trades data with, so it isn't settling on-chain every time it talks to someone. Then don't fill the wait with small talk, go straight on. Leave your terminal visible in a corner if your layout allows.
WHILE YOU WAIT
A postage batch is the right to write data on Swarm.
depth | "volume" How much you can upload with it |
amount | "duration" How long what you upload stays |
swarm-cli calls it a stamp. Same thing.
22/35
Presenter note
One purchase, two dials. Most confusion about Swarm pricing is someone turning one dial and expecting the other to move — say that line, it's what makes batches click.
WHILE YOU WAITreference
What a batch costs
| Depth | Capacity | 1 week | 1 month | 3 months |
|---|---|---|---|---|
| 17 | ~41 kB | 0.13 | 0.57 | 1.71 |
| 18 | ~6.1 MB | 0.26 | 1.14 | 3.42 |
| 19 | ~102 MB | 0.52 | 2.28 | 6.84 |
| 20 | ~629 MB | 1.05 | 4.56 | 13.68 |
| 22 | ~7.1 GB | 4.19 | 18.24 | 54.72 |
Costs in xBZZ, at the storage price on the day this was written.
The network moves that price with demand. swarm-cli status prints today's, and swarm-cli stamp create quotes a batch before it asks you to confirm.
23/35
Presenter note
Reference slide. Don't read the table out. Say one thing: these are the sizes you actually get, and the xBZZ columns move with the network price. Optional out loud; keep it on the page.
WHILE YOU WAIT
Your first batch will be tiny, on purpose.
| Buy | depth 17 — ~41 kB, about a week, ~0.13 xBZZ |
| Don't buy | depth 22 — ~4.2 xBZZ for the same week, far more than the ~0.20 you funded |
Batches can be extended later, so starting small costs you nothing but a second purchase.
24/35
Presenter note
Set expectations hard here, because otherwise the disappointment arrives mid-purchase. The depth-22 row isn't a warning about waste, it's a purchase that fails outright on the balance they were told to fund. 41 kB proves the round trip; it's nowhere near enough for a video or an image gallery. Buy small to learn, then buy for real once you know what you're storing.
WHILE YOU WAIT
Storage is rented, not bought.
TTL is the seconds left on the batch. At zero, the network is free to drop what it was holding.
25/35
Presenter note
The single most misunderstood thing about Swarm, and the one that bites at demo time. Point forward to the close: top up before anyone important looks at your project. By now the sync should be close — check the terminal.
BUY STORAGE
Check the sync gap before you spend anything
swarm-cli statusChainsync tells you how far behind the chain your node is. Wait until it's caught up.
26/35
Presenter note
If your own node is still behind, say so and show the wait before cutting it. Faking a clean run teaches people to skip the check.
BUY STORAGE
Buy your first batch
swarm-cli stamp createIt asks for a capacity, then a TTL. Answer 40KB and 1w. It works out the rest, shows you the cost, and waits for you to confirm.
waitThen it waits for the batch to go live before printing the ID. A couple of minutes.
Save the stamp ID. You'll paste it into everything from here on.
swarm-cli takes the same thing as flags — --capacity, --ttl, --label — and stamp buy takes a raw depth and amount if you ever need them.
27/35
Presenter note
Run it bare and answer the prompts. The point of doing it this way: you never work out a depth or an amount, you say what you want and it prices it. It prints your balance next to the cost and refuses outright if you can't cover it — that's the tiny-batch mistake, caught politely. It then blocks until the batch reports usable, so the wait card is a real wait — hold on the slide. Say the “save the ID” line twice; people lose it constantly.
PROVE IT
Up, then back down
echo "Hello Swarm" \
| swarm-cli upload --stdin \
--stamp <ID> --name hello.txtswarm-cli download <RETURNED_HASH>--stdin | Take the data from the pipe, instead of a file path |
--stamp | Which batch to take the stamp from |
--name | What the file is called once it's on Swarm |
The upload returns a reference. Anyone who has it can download the content.
28/35
Presenter note
If Hello Swarm comes back, they're done: node running, funded, storage paid, data stored and retrieved. This is the finish line from the second slide — call it out explicitly. The stamp ID is the one they saved two slides ago; that's the payoff for having saved it.
PROVE IT
That hash is the file.
29/35
Presenter note
Bridge to what they might build: this is the property people put evidence, archives and citations on. Thirty seconds, no more — the close does the building talk. If someone asks how you ever update anything, the answer is feeds and it's on the closing slide; don't take the detour here.
THE OTHER LANES
You took the terminal.
Here are the other two.
| Agent | /swarm-setup-bee in Claude Code | Install, funding and first stamp, in the same order |
| Swarm Desktop | ethswarm.org/build/desktop | A GUI, no terminal. Starts ultra-light — download only |
Switch Desktop to light in its configuration before you upload.
30/35
Presenter note
Deliberately last, not first — they've seen every command, so these read as routes they can audit rather than black boxes. Give the two equal weight and say why: not everyone has an agent, and not everyone wants one. Swarm Desktop is a real option, not a consolation prize — but say the ultra-light default out loud, because someone who installs it and expects to upload will hit the same wall we spent the funding section avoiding.
WHERE IT BREAKSreference
Six common pitfalls
| Funding the wrong address | swarm-cli addresses prints several. Only the Ethereum one takes funds. |
| Bringing your own RPC endpoint | It has to be a full archival node. Anything else gives storage: not found. |
| Buying more storage than you funded | Depth 17 ≈ 0.13 xBZZ. Depth 22 needs ~4.2 xBZZ for the same week. |
| Hardcoding the storage price | Ask for a capacity and a TTL and let the tooling price it. |
| Losing the stamp ID | swarm-cli stamp list prints it again. |
| Letting the batch expire | Nothing warns you. Top it up before the TTL runs out. |
31/35
Presenter note
Reference slide, and the one most worth linking in Discord. On the agent lane, add: agents make these too, so keep it open next to your terminal. Worth doing live: run an oversized batch buy against a wallet that can't cover it, let it fail, then do the depth-17 buy that works — thirty seconds, and it inoculates people against the most common way this goes wrong.
WHERE IT BREAKS
Still stuck? Stop.
discord.ethswarm.org · docs.ethswarm.org
Check the docs. Ask for help.
32/35
Presenter note
Mean it, and make sure it's true — this slide is the only support this page has. Nobody can unblock someone working through it alone, so the channel behind it has to be one that gets read. If you're wrapping this workshop into an event, this is the slide where the event's own channel gets swapped in.
WHAT NEXT
You have a node. Now use it.
| Upload a folder | The same command, pointed at a directory |
| Host a website | A folder with an index.html, hosted with nothing to patch |
| Feeds | Static addresses for content you intend to change |
| Build an app | create-swarm-app to scaffold, or bee-js in what you already have |
| Give it a name | Point an ENS name at the hash. It resolves on bzz.link |
| Access control (ACT) | Encrypt chunks and grant access by wallet key |
| Messaging | GSOC — the receiving node has to be a full node |
33/35
Presenter note
Keep it under 90 seconds. Say the through-line once: every item on this list assumes a node you control, so the hour they just spent is the prerequisite for all of it. The links come after the appendix — end here on the invitation to go and build something.
APPENDIXreference
Every command, in order
# check
node --version && npm --version
# install
npm install --global @ethersphere/swarm-cli
swarm-cli quickstart
bee version
# run, unfunded
bee start --password YOUR_PASSWORD \
--api-addr 127.0.0.1:1633
swarm-cli status
swarm-cli download <HASH>
# fund — send xDAI + xBZZ to the
# Ethereum address, on Gnosis Chain
swarm-cli addresses# run, funded
bee start --password YOUR_PASSWORD \
--swap-enable \
--api-addr 127.0.0.1:1633 \
--blockchain-rpc-endpoint \
https://xdai.fairdatasociety.org
swarm-cli status # wait until it is caught up
# buy storage
swarm-cli stamp create --capacity 40KB \
--ttl 1w --label first-stamp
swarm-cli stamp list
# prove it
echo "Hello Swarm" | swarm-cli upload \
--stdin --stamp <ID> --name hello.txt
swarm-cli download <RETURNED_HASH>
# keep it alive
swarm-cli stamp topup --stamp <ID> \
--amount <more>34/35
REFERENCES
Where to find all of this again
| links.ethswarm.org | Every Swarm link, in one place |
| docs.ethswarm.org | The official documentation of Bee |
| discord.ethswarm.org | Ask a question, join a discussion |
| swarm-devrel.bzz.link | A cheatsheet, served from Swarm |
| github.com/ethersphere | Bee, swarm-cli and bee-js, open-sourced |
These slides: commons3nse.swarm-devrel.bzz.link/how-to-run-a-node
35/35
Presenter note
The QR goes to links.ethswarm.org, which is the one address worth remembering — everything else hangs off it. Hold here while people photograph it.