Skip to main content

Install Bee

The swarm thrives on decentralisation, and Bee is designed so that it works best when many individuals contribute to the health and distributed nature of the system by each running a Bee node.

It is easy to set up Bee on small and inexpensive computers, such as a Raspberry Pi 4, spare hardware you have lying around, or even a cheap cloud hosted VPS (we recommend small, independent providers and colocations).

Installing Bee#

To install Bee you will need to go through the following process.

  1. Install Bee and set it up to run as a service.
  2. Configure Bee.
  3. Fund your node with XDAI and BZZ for the mainnet and gETH and gBZZ for our testnet.
  4. Wait for your chequebook transactions to complete and batch store to update.
  5. Back up your keys.
  6. Check Bee is working.

We do not recommend that you retain a large value of BZZ or XDAI in your nodes wallet. Please consider regularly removing accumulated funds. For added security, you may also want to consider running Bee-Clef

1. Install Bee#

Bee is packaged for Debian (Ubuntu), Centos, and MacOS using Homebrew.


sudo dpkg -i bee_1.8.2_amd64.deb

ARM (Raspberry Pi)#

sudo dpkg -i bee_1.8.2_armhf.deb
sudo dpkg -i bee_1.8.2_arm64.deb

If your system is not supported, please see the manual installation section for information on how to install Bee.

If you would like to run a hive of many Bees, checkout the node hive operators section for information on how to operate and monitor many Bees at once.

2. Configure Bee#

Bee is a versatile piece of software with diverse use cases. Before starting Bee for the first time you will need to configure it to suit your needs.

Edit Config File#

To alter Bee's configuration, edit the relevant configuration file (default /etc/bee/bee.yaml), and then restart your Bee service.


sudo vi /etc/bee/bee.yaml
sudo systemctl restart bee

Important Configuration#

Full Node, Light Node#

Bee nodes default to run in light-mode. If you want to contribute your resources to provide services to the network in exchange for bandwidth in kind and perhaps even BZZ, simply set the --full-node flag to true.

full-node: true

NAT Address#

Swarm is all about sharing and storing chunks of data. To enable other Bees (also known as peers) to connect to your Bee, you must broadcast your public IP address, and ensure that Bee is reachable on the correct p2p port (default 1634). We recommend that you manually configure your external IP and check connectivity to ensure your Bee is able to receive connections from other peers.

First determine your public IP address:


Then configure your node, including your p2p port (default 1634).

nat-addr: ""

Blockchain RPC Endpoints#

Your Bee node must have stable access to a Gnosis Chain RPC endpoint, so that it can interact with and deploy your chequebook contract, and see the latest view of the current postage batches, as well as to interact with and top up your own batches.

We recommend you run your own Gnosis Chain Node. If you do not wish to sync your own nodes, and are willing to trust a third party, you may also like to consider using a RPC endpoint provider such as GetBlock.

By default, Bee expects a local Gnosis Chain node at ws://localhost:8545. To use a Gnosis Chain RPC provider instead, change your configuration to use the API endpoint URL they provide, for example:


Funding Your Chequebook (Optional)#

You may select how much BZZ to fund your wallet with. If you are happy to stay within the free usage limits initially, you may even select 0.

swap-initial-deposit: 0

We suggest We recommend 1 BZZ, 10000000000000000 PLUR as a good starter amount, but you can start with more if you will be paying for a lot of interaction with the network.

ENS Resolution (Optional)#

The ENS domain resolution system is used to host websites on Bee, and in order to use this your Bee must be connected to an Ethereum blockchain node on the main network. If you would like to browse the swarm We recommend you sign up to Infura's API service and set your --resolver-options=

resolver-options: ["<<your-api-key>>"]

Open File Descriptors (Optional)#

Bee is designed to work on a lot of different hardware configurations. To facilitate the exploration of this, during our beeta phase, we have given node operators access to leveldb's --db-open-files-limit. This helps determine the speed with which Bee can read and write to its database, and therefore its efficiency in forwarding and serving chunks. Some say setting this to much more than the default 200 leads to a much enhanced ability to participate in the swarm and get those BZZ! Share your experience in the #node-operators channel of our Discord server to help us make this process more automated in the future.

db-open-files-limit: 2000

Fund Your Bee#

Your Bee must deploy a chequebook contract to keep track of its exchanges with other Bees in the Swarm. To do that it XDAI and optionally xBZZ.

First, find out your Bee's Ethereum address:


sudo bee-get-addr

Once you have determined your Bee's Ethereum address, fund your node with XDAI and xBZZ

If too much time has elapsed, you may need to restart your node at this point.


sudo systemctl restart bee

Wait for Initialisation#

When first started, Bee must deploy a chequebook to the Gnosis Chain blockchain, and sync the postage stamp batch store so that it can check chunks for validity when storing or forwarding them. This can take a while, so please be patient! Once this is complete, you will see Bee starting to add peers and connect to the network.

You can keep an eye on progress by watching the logs while this is taking place.


journalctl --lines=100 --follow --unit bee

While you are waiting for Bee to initalise, this is a great time to back up your keys so you can them safe.

Check Bee Is Working#

Once Bee has been funded, the chequebook deployed, and postage stamp batch store synced, its HTTP API will start listening at localhost:1633.

To check everything is working as expected, send a GET request to localhost port 1633.

curl localhost:1633
Ethereum Swarm Bee

Great! Our API is listening!

Next, let's see if we have connected with any peers by querying our Debug API.


Here we are using the jq utility to parse our javascript. Use your package manager to install jq, or simply remove everything after and including the first | to view the raw json without it.

curl -s localhost:1635/peers | jq ".peers | length"

Perfect! We are accumulating peers, this means you are connected to the network, and ready to start using Bee to upload and download content or host and browse websites hosted on the Swarm network - and accumulating cheques tht you can cashout to get your BZZ.

Welcome to the swarm! ๐Ÿย ๐Ÿย ๐Ÿย ๐Ÿย ๐Ÿ