Menu
Reference guide to install Bee and swarm-cli, fund and upgrade to light mode, buy a stamp, and verify end-to-end uploads.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Guide to Swarm ACT encryption and access control: create grantees, upload protected data, grant/revoke access, and troubleshoot not-found/history issues.
Build and publish a Swarm blog with a permanent feed-manifest URL, post management workflow, and optional ENS domain mapping.
Scaffold a Swarm app or add bee-js to an existing project, with core upload/download patterns and node-compatibility guidance.
Answer Swarm conceptual questions from official docs with source links; use for APIs, behavior, configuration, and architecture clarifications.
Create and manage Swarm feeds for stable, updateable URLs using bee-js or swarm-cli, including manifest creation and feed updates.
Deploy and update static websites on Swarm via one-off or feed-based publishing, with optional ENS integration and stamp lifecycle notes.
| name | setup-bee |
| description | Reference guide to install Bee and swarm-cli, fund and upgrade to light mode, buy a stamp, and verify end-to-end uploads. |
| user-invocable | true |
Guide a developer through getting a Bee light node running so they can build on Swarm.
Run these checks now — do not just show the commands to the user:
Detect platform:
uname -s
Fetch the latest Bee version tag:
curl -s https://api.github.com/repos/ethersphere/bee/releases/latest | jq -r .tag_name
Use this tag in the install command below (replace TAG value).
| Mode | Can download | Can upload | Needs funding | Use case |
|---|---|---|---|---|
| Ultra-light | Yes | No | No | Exploring the API, downloading data |
| Light | Yes | Yes | Yes (~0.01 xDAI + ~0.2 xBZZ) | Development, uploads, feeds |
| Full | Yes | Yes | Yes + staking | Running infrastructure, PSS subscribe |
Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y curl
macOS: Pre-installed. If missing: brew install curl
Ubuntu/Debian — via NodeSource (recommended, gets Node 20):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
Ubuntu 24.04 — via apt (gets Node 18 from Ubuntu repos):
sudo apt-get update && sudo apt-get install -y nodejs npm
macOS — via Homebrew:
brew install node
Linux/macOS — via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc # or ~/.zshrc on macOS
nvm install --lts
Windows: Install WSL2 first (wsl --install in PowerShell as Administrator, then restart), then follow the Linux path inside WSL2.
Verify: node --version && npm --version — Node.js should be v18 or higher.
~0.01 xDAI + ~0.2 xBZZ — not needed for ultra-light mode.
curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=<LATEST_TAG> sudo bash
Or with wget:
wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=<LATEST_TAG> sudo bash
Verify: bee version
Install swarm-cli:
npm install -g @ethersphere/swarm-cli
No funding needed — lets you explore the API and download data immediately.
bee start \
--password YOUR_SECURE_PASSWORD \
--api-addr 127.0.0.1:1633
Verify it's running (the node may return 503 for 10–30 seconds while initializing — this is normal, wait a moment and retry):
swarm-cli status
Get your wallet address:
swarm-cli addresses
Send tokens to this address on Gnosis Chain (not Ethereum mainnet):
Option A — Redeem a gift code (fastest)
If the developer has a gift code (a private key from Swarm), redeem it directly to the Bee wallet:
swarm-cli utility redeem <GIFT_CODE_PRIVATE_KEY> --json-rpc-url https://xdai.fairdatasociety.org
This transfers xBZZ and xDAI from the gift wallet to the Bee node wallet automatically. The node's wallet address is detected from the running Bee node. If the command fails with a 429 error, try --json-rpc-url https://rpc.gnosischain.com instead.
To redeem to a specific wallet instead:
swarm-cli utility redeem <GIFT_CODE_PRIVATE_KEY> --target <WALLET_ADDRESS>
Option B — Multichain top-up (any chain/token, no bridging)
Option C — Manual
xDAI from Gnosis faucets (https://docs.gnosischain.com/tools/Faucets) or bridge (https://bridge.gnosischain.com/). xBZZ from exchanges (https://www.ethswarm.org/get-bzz).
Stop the ultra-light node (Ctrl+C), then restart with swap enabled:
bee start \
--password YOUR_SECURE_PASSWORD \
--swap-enable \
--api-addr 127.0.0.1:1633 \
--blockchain-rpc-endpoint https://xdai.fairdatasociety.org
xdai.fairdatasociety.org is the Ethersphere-maintained endpoint and is archival — required for Bee to sync historical stamp batch data on first start. If it returns 429 (rate limited), try https://rpc.gnosischain.com or https://gnosis-rpc.publicnode.com as short-term fallbacks, but note these are not archival nodes and may produce an incomplete stamp batch list on first sync. For production use, a dedicated archival RPC from Ankr, QuickNode, or Alchemy is recommended.
The node deploys a chequebook and syncs chain data (~5 minutes). Monitor:
swarm-cli status
When the Δ (blocks behind) in Chainsync drops to less than ~10, your node is ready.
Required before any upload.
swarm-cli stamp create
Enter capacity (e.g. 500MB, 1GB) and TTL (e.g. 1w, 1month, 1y). The command shows the cost in xBZZ and asks for confirmation before purchasing. Save the Stamp ID returned.
For detailed sizing and management options, see /stamps.
swarm-cli stamp list
swarm-cli stamp show <stamp-id>
swarm-cli stamp topup --stamp <stamp-id> --amount <amount>
# Upload
echo "Hello Swarm" | swarm-cli upload --stdin --stamp <BATCH_ID> --name hello.txt
# Download
swarm-cli download <SWARM_HASH>
# File saved to <SWARM_HASH>/hello.txt
cat <SWARM_HASH>/hello.txt
# Upload (PowerShell)
"Hello Swarm" | swarm-cli upload --stdin --stamp <BATCH_ID> --name hello.txt
# Download verification (PowerShell)
Get-Content <SWARM_HASH>/hello.txt
If Hello Swarm is printed, the node is fully operational.
Always bind API to localhost (127.0.0.1:1633). Never expose port 1633 to the public internet.
For any conceptual or technical question not covered by the steps above, invoke /docs to find the relevant authoritative source rather than answering from prior knowledge.
bee start --help