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. 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/37

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 viewer 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.

Your node is a client. Once data is uploaded it lives with the peers, so closing the laptop doesn't take it offline.

03/37

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.

WHY RUN YOUR OWN

You could use someone else's node. This is what running your own gets you.

	Someone else's node	Your own node
Writing	Their account, their limits	Your postage batch
How long data stays	Whatever they paid for	You decide, and you can extend it
Endpoint	A remote API	`http://localhost:1633`
Ceiling	What their API exposes	Everything Bee can do

Reading from a public gateway needs nothing at all. It's writing — and deciding what stays — where your own node starts to matter.

04/37

Presenter note

This is the slide that answers “why am I watching this?” for a developer. Say the last row out loud: feeds, access control and messaging all assume a node you control, so this hour is the prerequisite for everything in the closing slide.

WHAT YOU LEAVE WITH

By the end of this video 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/37

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 RECORDING

Follow along 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/37

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 modes. You're building the middle one.

Mode	Download	Upload	Shares disk	Needs funding
Ultra-light	Yes	No	No	No
Light	Yes	Yes	No	~0.01 xDAI + ~0.20 xBZZ
Full	Yes	Yes	Yes	Plus stake

“A ‘light' node can download and upload data from Swarm but does not share its disk space with the network and does not earn rewards.”

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 LANEreference

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

	What you need	What drives it	Best if
Agent — demoed	Node.js 18+, Claude Code	`/swarm`	You want the tedium handled
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.

08/37

Presenter note

Say explicitly that nobody is behind if they're not on the agent lane. 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.

WHEN IT GOES WRONG

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

Terminal fighting you	Swarm Desktop
No node at all today	Beeport (beta) — uploads from the browser

Beeport uses someone else's node, so nothing you learn here transfers. Plan C, not a lane.

09/37

Presenter note

Give permission early and explicitly. Ten minutes lost to an install is ten minutes not spent building.

INSTALL

Two installs and a binary. Nothing to configure.

10/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.

11/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 --global @ethersphere/swarm-cli

12/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.

The documented installer, if you prefer it: curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.1 bash

13/37

Presenter note

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

INSTALL · STEP 4

Confirm it landed

bee version

Expect 2.8.1 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.

14/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

Ultra-light mode	Downloads work now
	Uploads need funding — next section

15/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.

16/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.

17/37

Presenter note

The nicest moment in the session — make it land. Publish this page first, so the hash is fixed and verified before anyone watches.

HOW YOU PAY

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

No account. No sign-up. No card.

18/37

Presenter note

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

WHY UPLOADS COST

Downloads are free. Uploads are not.

Download	Free tier — no batch needed
Upload	Needs a postage batch

“Postage stamp batches represent *right to write* data on Swarm's DISC.”

19/37

Presenter note

Frame it as the feature it is, not as friction to apologize for: the payment is what makes the storage stay there without a company behind it.

WHAT YOU NEED

Two tokens, both on Gnosis Chain.

Token	Amount	What the docs say
xDAI	~0.01	“enough to start a light node”
xBZZ	~0.20	“enough to upload a small amount of data”

Not Ethereum mainnet. Gnosis Chain.

20/37

Presenter note

The slide that replaces hand-waving about cost with a number, and they're the documentation's own numbers. 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 · Omnibridge	Buying xBZZ directly, or bringing BZZ over from mainnet
Gnosis faucet	You only need the xDAI for gas

swarm-cli addresses          # where to send it

21/37

Presenter note

Run swarm-cli addresses on camera and point at the address. 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.

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 batch history. The public fallbacks aren't archival and can give you an incomplete batch 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.

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 chequebook contract will be automatically deployed when a Bee node is configured to run as a light or full node… Required for bandwidth payments.”
Reading chain history	Catching up on which batches have paid for what, so it knows which data the network owes you.

24/37

Presenter note

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.

WHILE YOU WAIT

A postage batch is the right to write data on Swarm.

`depth`	“determining data volume that can be uploaded by the batch”
`amount`	“determining storage duration of data uploaded with the batch”

swarm-cli calls it a stamp. Same thing.

25/37

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	~40 KB	0.12	0.5	1.6
18	~6 MB	0.24	1.0	3.2
19	~110 MB	0.5	2.1	6.3
20	~680 MB	1.0	4.2	12.6
22	~7.7 GB	3.9	16.8	50.4

xBZZ, rough upper bounds. cost ≈ amount × 2^depth ÷ 10^16 — read the live price rather than hardcoding it: 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 the network price, so read the price. Optional on camera; keep it on the page.

WHILE YOU WAIT

Your first batch will be tiny, on purpose.

Buy	depth 17 — ~40 KB, about a week, ~0.12 xBZZ
Don't buy	depth 22 — ~4 xBZZ for the same week, and it fails on a thin balance

Batches can be extended later, so starting small costs you nothing but a second purchase.

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. Buy small to learn, then buy for real once you know what you're storing.

WHILE YOU WAIT

Storage is rented, not bought.

The address is permanent. The storage behind it is rented — let the batch lapse and the data stops being served.

TTL is “the number of seconds before the chunks will be considered for garbage collection by nodes in the network.”

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 batch 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 batch that doesn't work.

BUY STORAGE

Buy your first batch

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

By the dials instead: swarm-cli stamp buy --depth 17 --amount <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 batch needs about two minutes. Same deal.

A batch has 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>

“The upload returns a Swarm reference hash, anyone with that reference can download the content.”

32/37

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.

PROVE IT

That hash is the file.

The address is the hash of the content, which is what makes it possible to verify the integrity of chunk data.

A feed address is the deliberate exception — “static addresses for your mutable content.”

33/37

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.

WHERE IT BREAKSreference

Five things that will waste your afternoon

Buying more storage than you funded	Depth 17 ≈ 0.12 xBZZ. Depth 22 needs ~4 xBZZ for the same week.
Hardcoding the storage price	It's live. Read `/chainstate`.
Full-node code on a light node	Subscribing to incoming messages is the usual casualty.
Building “unsend” on ACT	“Grantees will be able to retrieve the content version they were granted access to… even if their access to newer versions were revoked.”
The SDK's version warning	Stale version string in bee-js, not a real problem.

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 it open next to your terminal. Because this is recorded, actually run an oversized batch 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 · docs.ethswarm.org

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

Thank you

Access control (ACT)	Encryption at the chunk level — grant access by wallet public key
Feeds	“Static addresses for your mutable content”
Websites	A folder with an `index.html`, hosted with nothing to patch
Messaging	GSOC and PSS

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

links.ethswarm.org · docs.ethswarm.org · swarm-devrel.bzz.link · 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