How to run a Bee node

SWARM WORKSHOP · 01

How to run a Bee node

Install it, fund it, store something, get it back.

01/37

Presenter note

Face cam. Name, role, one sentence on Swarm Foundation. Don't explain the agenda yet — the next two slides do it better.

WHAT YOU LEAVE WITH

You'll finish with a funded node, a paid-up stamp, and a file you can prove you stored.

Forty-five minutes of video. About an hour on your own machine. No prior Swarm experience assumed.

02/37

Presenter note

Say it plainly, then stop talking for a beat. This is the contract. Naming both numbers up front is what stops people bailing at minute twenty because they thought this was a forty-five minute job.

HOW TO USE THIS RECORDING

Follow along, and pause without guilt.

Every command is on a slide on this page — you never have to scrub the video to copy-paste. Two points have real waits; a card tells you when.

Funding a node used to be where people gave up on Swarm. It's about four minutes now.

Stuck? discord.ethswarm.org — someone's reading it.

0:02  what Swarm is        0:24  how it works
0:06  pick your lane       0:31  buy + upload
0:09  install              0:38  what breaks
0:14  first download       0:42  what next
0:18  funding

03/37

Presenter note

This slide replaces everything 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.

WHAT SWARM IS

Somewhere to put data that isn't a company's server.

Held and served by thousands of independent machines, rather than one provider who logs who uploaded what and when.

04/37

Presenter note

Resist the urge to list features. One idea per slide.

HOW YOU PAY

You buy space directly. An amount of storage, for a length of time.

No account. No sign-up. No card. It's a subscription you hold — not a platform account that holds you.

05/37

Presenter note

This lands better than any technical explanation. Flag the flip side now so slide 28 isn't a surprise: a subscription you hold is also one you have to renew.

WHAT A NODE ACTUALLY IS

Your node is a way in, not a server you maintain.

It finds peers, pays them for your uploads, and fetches your data back. Nothing points at it. Nobody visits it. You can close the laptop.

06/37

Presenter note

Kills the most common beginner fear — “am I now running infrastructure?” No. Worth 40 seconds if you have them. Optional: cut first if the edit runs long.

THE ONE TABLE THAT MATTERSreference

Three modes. You're building the middle one.

Mode	Download	Upload	Needs funding
Ultra-light	Yes	No	No
Light	Yes	Yes	Yes — xDAI + xBZZ on Gnosis Chain
Full	Yes	Yes	Yes, plus staking

A light node covers everything in this workshop. Some messaging features need a full node.

07/37

Presenter note

Reference slide — tell them to bookmark it. Say the plan out loud: we start ultra-light because it's free 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.

PICK YOUR LANE

Three ways to run a node. I'm doing the first one.

The other two are on the next slide, and both end in the same place: a funded node and a file on Swarm.

08/37

Presenter note

Say explicitly that nobody is behind if they're not on the agent lane.

PICK YOUR LANEreference

Same destination, different vehicle

	What you need	What drives it	Best if
Agent — demoed	Node.js 18+, Claude Code	`/swarm`	You want the tedium handled and your time on architecture
Terminal	Node.js 18+, a shell	You, copy-pasting this page	You'd rather read than delegate
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.

09/37

Presenter note

Reference slide. Name Swarm Desktop by version so it's findable: v0.55.1, from ethswarm.org/build/desktop. Say it's beta, say it works, say the CLI is what everything downstream assumes.

WHEN IT GOES WRONG

If your install breaks, don't grind. Switch lanes.

Desktop app if the terminal is fighting you. And if you want to ship something today without a node at all, Beeport (beta) uploads from the browser — though you're then using someone else's node, not running one.

10/37

Presenter note

Beeport caveat matters: you're paying per upload through someone else's node rather than running one, so nothing you learn here transfers. Mention it as a Plan C, not a lane.

INSTALL

Two installs and a binary. Nothing to configure.

11/37

Presenter note

Switch to screen share here and stay there until the sync wait.

INSTALL · STEP 1

Check what you already have

node --version && npm --version

v18 or newer. Anything older and Bee's tooling misbehaves in ways that look like network problems.

12/37

Presenter note

On the agent lane this is the first thing /swarm checks for you — say so, and show it checking. The point of the slide is that they can see what it checked.

INSTALL · STEP 2

The CLI comes first — it can fetch Bee for you

npm install -g @ethersphere/swarm-cli

Version 3.4.0 or newer.

13/37

Presenter note

Explain the ordering, it's counterintuitive. swarm-cli is the thing you'll live in; Bee is the binary it talks to.

INSTALL · STEP 3

Download the node

swarm-cli quickstart

Grabs the right Bee binary for your platform. No sudo, no piping a script from the internet into your shell.

Prefer the official installer? curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.0 sudo bash

14/37

Presenter note

The orange thing on this slide is the command. Say why you're not using the curl-pipe-sudo one-liner on camera: nobody should be trained to paste that reflexively.

INSTALL · STEP 4

Confirm it landed

bee version

Expect 2.8.0 or newer. Do not run 2.7.x — 2.8 was a breaking change.

If this prints a version, you're past the only genuinely fiddly part.

15/37

Presenter note

Say the reassuring line. People who've been fighting an install for ten minutes need to hear that the rest is downhill.

RUN IT · NO FUNDING YET

Start it with no money at all

bee start \
  --password YOUR_PASSWORD \
  --api-addr 127.0.0.1:1633

That's ultra-light mode. Downloads work immediately. Uploads don't — that's the next section.

16/37

Presenter note

Make up a password on camera and say out loud that you're writing it down, because they need the same one after funding. This is a real trip hazard. 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 status

The node is waking up and finding peers. Wait, retry, don't debug it.

17/37

Presenter note

Show the 503 happening if you can. Seeing the scary thing be fine on camera is worth more than being told it's fine.

RUN IT

Pull something off Swarm before you've paid a cent

swarm-cli download <HASH>

These slides are on Swarm. That's the hash. Your brand-new node just fetched the thing you're looking at.

18/37

Presenter note

The nicest moment in the session — make it land. Being pre-recorded helps: publish this page first, and the hash is fixed and verified before anyone watches.

WHY UPLOADS COST

Downloads are free. Uploads are not.

You're paying thousands of independent machines to keep your data and serve it. That payment is the whole reason it stays available without a company behind it.

19/37

Presenter note

Frame it as the feature it is, not as friction to apologize for.

WHAT YOU NEED

Two tokens, both on Gnosis Chain.

xDAI — gas. About 0.01 covers deploying your chequebook and buying a stamp.

xBZZ — the storage itself. How much depends entirely on how much space, for how long.

	~40 KB	~110 MB	~680 MB
1 week	0.12 xBZZ	0.5 xBZZ	1 xBZZ
1 month	0.5 xBZZ	2 xBZZ	4 xBZZ
3 months	1.6 xBZZ	6 xBZZ	13 xBZZ

Rough upper bounds — the real price is live, and often ~40% lower.

20/37

Presenter note

The slide that replaces hand-waving about cost with a number. People can decide whether they're in before they've installed anything. Two things to say out loud: the smallest useful stamp costs about 0.12 xBZZ, barely a tenth of a token, so the barrier is getting tokens at all rather than the amount; and these track a live network price, so treat the table as an order of magnitude.

WHAT YOU NEED

Three routes, easiest first

Multichain top-up — fund.bzz.limo · Pay from whatever chain and token you already hold. No bridging, no swapping.
Buy xBZZ directly on Gnosis Chain · CoW Swap on Gnosis, or Jumper cross-chain. Already on Ethereum mainnet? Omnibridge brings BZZ across.
xDAI only — a faucet · Gnosis faucets cover the gas. They won't give you xBZZ.

Your node's address: swarm-cli addresses

21/37

Presenter note

Run swarm-cli addresses on camera and point at the address — funds go there on Gnosis Chain, not Ethereum mainnet. Say that twice; it's the one mistake here that loses money. 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. Note that fund.bzz.limo is itself served from Swarm.

UPGRADE TO A LIGHT NODE

Same node. Swap enabled. Now it can pay.

bee start \
  --password YOUR_PASSWORD \
  --swap-enable \
  --api-addr 127.0.0.1:1633 \
  --blockchain-rpc-endpoint https://xdai.fairdatasociety.org

Same password as before. Ctrl+C the old one first.

22/37

Presenter note

Say why that specific RPC: it's archival, which Bee needs on first start to read stamp history. The public fallbacks aren't archival and can give you an incomplete stamp list.

UPGRADE TO A LIGHT NODE

It's deploying a chequebook and reading chain history. About five minutes.

pauseYour node is syncing. Let this play, or pause and come back.

Leave it running. The next five slides are the ones worth listening to anyway.

23/37

Presenter note

The pivot into the teaching block, and the first pause card. Don't fill the wait with small talk — go straight on. Leave your terminal visible in a corner if your layout allows, then cut the remaining minutes in the edit.

WHILE YOU WAIT

What your node is doing right now

Deploying a chequebook — a prepaid tab with the peers it trades data with, so it isn't settling on-chain every time it talks to someone.

Reading stamp history — catching up on who has paid for what storage, so it knows which data the network owes you.

24/37

Presenter note

Analogies land here. The chequebook is a bar tab; the stamp history is the network's ledger of paid-up rent.

WHILE YOU WAIT

A postage stamp is prepaid storage.

Depth is how much space. Amount is how long it lasts.

One purchase, two dials. Most confusion about Swarm pricing is someone turning one dial and expecting the other to move.

25/37

Presenter note

Say the last line — it's the sentence that makes stamps click.

WHILE YOU WAITreference

Stamp sizing, for when you buy in earnest

Depth	Realistic capacity	Duration	Amount (approx.)
17	~40 KB	1 week	9,345,732,487
18	~6 MB	1 month	40,053,139,205
19	~110 MB	3 months	120,159,417,615
20	~680 MB	6 months	240,318,835,230
21	~2.6 GB	1 year	480,637,670,460
22	~7.7 GB

Cost in xBZZ ≈ amount × 2^depth ÷ 10^16. Upper bounds — read the live price: curl -s http://localhost:1633/chainstate | jq .currentPrice

26/37

Presenter note

Reference slide. Don't read the table out. Say one thing: the numbers move with network price, so read the price, never hardcode it. Optional on camera; keep it on the page.

WHILE YOU WAIT

Your first stamp will be tiny, on purpose.

Buy depth 17 first — ~40 KB for about a week, roughly 0.12 xBZZ. Enough to prove the whole round trip.

Reach for depth 22 and you'll need ~4 xBZZ for the same week. It will fail, and the error won't tell you why.

27/37

Presenter note

Set expectations hard here, because otherwise the disappointment arrives mid-purchase. 40 KB proves the round trip; it's nowhere near enough for a video or an image gallery. The useful mental model: buy small to learn, then buy for real once you know what you're storing. Stamps can be extended later, so starting small costs you nothing but a second purchase.

WHILE YOU WAIT

Storage is rented, not bought.

The address never changes — it's derived from the file's contents. Whether the file is still there depends on the space being paid up.

Let a stamp run down and your data stops being served. Top it up and it stays.

28/37

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 on camera.

BUY STORAGE

Check the sync gap before you spend anything

swarm-cli status

Chainsync Δ under ~10 blocks and you're ready. Buying while it's still catching up is how you get a stamp that doesn't work.

29/37

Presenter note

If your own node is still behind here, say so and show the wait before cutting it. Faking a clean run teaches people to skip the check — and then they buy a stamp that doesn't work.

BUY STORAGE

Buy your first stamp

swarm-cli stamp create --capacity 40KB --ttl 1w --label first-stamp

Prefer the dials directly? swarm-cli stamp buy --depth 17 --amount <computed from live price>

Save the stamp ID. You'll paste it into everything from here on.

30/37

Presenter note

Say the “save the ID” line twice. People lose it constantly.

BUY STORAGE

Give it two minutes before you use it

swarm-cli stamp list

pauseYour stamp needs about two minutes. Same deal.

A stamp needs to propagate before the network will honor it. Uploading immediately looks exactly like a broken node.

31/37

Presenter note

Second pause card. Short enough that you can hold on the slide and explain why propagation takes a moment, rather than cutting to black.

PROVE IT

Up, then back down

echo "Hello Swarm" | swarm-cli upload --stdin --stamp <ID> --name hello.txt

swarm-cli download <RETURNED_HASH>

If Hello Swarm comes back, you're done. Node running, funded, storage paid, data stored and retrieved.

32/37

Presenter note

This is the finish line from the second slide. Call it out explicitly — “that's the thing I promised you an hour ago.”

PROVE IT

That hash is the file.

It's derived from the contents, so change one byte and it's a different address. If a hash resolves, what's behind it is byte-identical to what you published.

That's the property people build evidence, archives and citations on.

A feed address is the deliberate exception — it's built to resolve to your newest version instead.

33/37

Presenter note

Bridge to what they might build. Thirty seconds, no more — the close does the building talk.

WHERE IT BREAKSreference

Five things that will waste your afternoon

Buying more storage than you funded. Depth 17 is right for a first demo, at ~0.12 xBZZ. Depth 22 needs ~4 xBZZ for the same week and fails on a thin balance.
Hardcoding the storage price. It's live. Read /chainstate.
Writing full-node code on a light node. Subscribing to incoming messages is the usual casualty. Check your mode first.
Building “unsend” on ACT. Revocation cuts off future and current updates. It cannot retract a file someone already downloaded.
The SDK's “unsupported version” warning. Stale version string in bee-js, not a real problem. Ignore it.

34/37

Presenter note

Reference slide, and the one most worth linking in Discord. On the agent lane, add: agents make all five of these, so keep this slide open next to your terminal. Use the format here — because this is recorded, actually run an oversized stamp buy on a thin balance and let it fail on camera, then cut to the depth-17 buy that works. Thirty seconds, and it inoculates people against the most common way this goes wrong.

WHERE IT BREAKS

Stuck for fifteen minutes? Stop.

discord.ethswarm.org — or the troubleshooting guide. Ask at hour two, not hour forty.

Nobody is impressed by suffering.

35/37

Presenter note

Mean it, and make sure it's true — this slide is the only support the video has. Nobody can unblock a viewer while it plays, so the channel behind this slide 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

Thank you

Your node can also: control who reads what (ACT) · keep one address that always resolves to your newest version (feeds) · host a site with nothing to patch · send encrypted notifications.

Before anyone looks at it: top up your stamp. swarm-cli stamp topup --stamp <ID> --amount <more> — a starter stamp lasts about a week, and a dead stamp looks exactly like a broken project.

Swarm Links hub: links.ethswarm.org · Docs: docs.ethswarm.org · Cheatsheet: swarm-devrel.bzz.link · Discord: discord.ethswarm.org

36/37

Presenter note

Back to face cam. Keep it under 90 seconds. End on the invitation to come and ask something, not on the list of links.

APPENDIXreference

Every command, in order

# check
node --version && npm --version

# install
npm install -g @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 this
# 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   # Chainsync delta < 10

# buy storage
swarm-cli stamp create --capacity 40KB \
  --ttl 1w --label first-stamp
swarm-cli stamp list          # wait ~2 min

# 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>

37/37