It is easy to set up a Bee light node 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). When running a full node however, it's important to meet the minimum required specifications.
Recommended Hardware Specifications
Minimum recommended specifications for each full node:
- Dual core, recent generation, 2ghz processor
- 8gb RAM
- 30gb SSD
- Stable internet connection
HDD drives are very strongly discouraged for full nodes due to their low speeds.
Note that there are additional hardware requirements if you choose to run your own Gnosis Chain node in order to provide your Bee node(s) with the required RPC endpoint. See configuration step for more details.
In order to test whether a set of hardware specs is sufficient for running a full node and participating in the storage incentives redistribution, see this guide on the staking page.
Light and UltraLight Nodes
The minimum required hardware specifications for light and ultralight nodes are very low, and can be run on practically any commercially available computer or microcomputer such as a Raspberry Pi.
Note on Startup Methods
bee start startup method may not be used interchangeably with running Bee as a service using
It is strongly advised to use run Bee using a service manager such as
Bee will be set up to run as a service automatically as part of the installation process if using one of the official Debian or RPM packages.
Bee may be operated either by using the
bee start command within a terminal session or by running Bee as a service in the background using
systemctl (Linux) and
brew services (MacOS) commands.
While the Bee service does use the
bee start command under the hood, there are two important differences between these modes of operation in practice:
When starting a node by directly using
bee startafter starting up a terminal session, the Bee node process is bound to that terminal session. When the session ends due to closing the terminal window or logging out from a remote ssh session, the node will stop running. When running bee as a service on the other hand, the node can continue to operate in the background even after the terminal session ends.
When running a Bee node using the
bee startcommand, a separate instance of Bee using different default locations for the config and data folders from the Bee service is used. The
bee startcommand uses
~/.bee.yamlas the default config directory and
~/.beeas the default data directory, while
/etc/bee/bee.yamlas the default config directory and
/var/lib/beeas the default data directory. See the configuration page for more details.
bee start may not be the best option for most users - especially if operating a full node.
- Install Bee
- Configure Bee
- Find Bee Address
- Fund node (Not required for ultra-light nodes)
- Wait for Initialisation
- Check Bee Status
- Back Up Keys
- Deposit Stake (Full node only, optional)
1. Install Bee
Package manager install
Bee is available for Linux in .rpm and .deb package format for a variety of system architectures, and is available for MacOS through Homebrew. See the releases page of the Bee repo for all available packages. One of the advantages of this method is that it automatically sets up Bee to run as a service as a part of the install process.
Get GPG key:
curl -fsSL https://repo.ethswarm.org/apt/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/ethersphere-apt-keyring.gpg
Set up repo inside apt-get sources:
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ethersphere-apt-keyring.gpg] https://repo.ethswarm.org/apt \
* *" | sudo tee /etc/apt/sources.list.d/ethersphere.list > /dev/null
sudo apt-get update
sudo apt-get install bee
Set up repo:
sudo echo "[ethersphere]
gpgcheck=0" > /etc/yum.repos.d/ethersphere.repo
yum install bee
brew tap ethersphere/tap
brew install swarm-bee
You should see the following output to your terminal after a successful install:
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
0 upgraded, 1 newly installed, 0 to remove and 37 not upgraded.
Need to get 0 B/27.2 MB of archives.
After this operation, 50.8 MB of additional disk space will be used.
Selecting previously unselected package bee.
(Reading database ... 82381 files and directories currently installed.)
Preparing to unpack .../archives/bee_1.17.4_amd64.deb ...
Unpacking bee (1.17.4) ...
Setting up bee (1.17.4) ...
Logs: journalctl -f -u bee.service
Bee requires a Gnosis Chain RPC endpoint to function. By default this is expected to be found at ws://localhost:8546.
Please see https://docs.ethswarm.org/docs/installation/install for more details on how to configure your node.
After you finish configuration run 'sudo bee-get-addr' and fund your node with XDAI, and also XBZZ if so desired.
Created symlink /etc/systemd/system/multi-user.target.wants/bee.service → /lib/systemd/system/bee.service.
Shell script install (Alternate method)
The Bee install shell script for Linux automatically detects its execution environment and installs the latest stable version of Bee.
Note that this install method copies precompiled binaries directly to the
/usr/local/bin directory, so Bee installed through this method cannot be managed or uninstalled with package managers such as
Also note that unlike the package install method, this install method will not set up Bee to run as a service (such as with systemctl or brew services).
Use either of the following commands to run the script and install Bee:
wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v1.17.4 bash
curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v1.17.4 bash
Build from source
If neither of the above methods works for your system, you can see our guide for building directly from source.
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. The installation script should have generated a config file at
/etc/bee/bee.yaml populated by the default configuration for the Bee service. See the configuration section for more details.
Check that the file was successfully generated and contains the default configuration:
test -f /etc/bee/bee.yaml && echo "$FILE exists."
The output should match the default bee.yaml values.
bee.yaml file is missing, create a new one and fill it in with the default configuration copied from the Ethswarm GitHub Bee repo.
sudo touch /etc/bee/bee.yaml
sudo vi /etc/bee/bee.yaml
Set node type
Full Node, Light Node, Ultra-light Node
See the quick start guide if you're not sure which type of node to run.
To run Bee as a full node both
swap-enable must be set to
true, and a valid and stable Gnosis Chain RPC endpoint must be specified with
To run Bee as a light node
full-node must be set to
swap-enable must both be set to
true, and a valid and stable Gnosis Chain RPC endpoint must be specified with
To run Bee as an ultra-light node
swap-enable must both be set to
false. No Gnosis Chain endpoint is required, and
blockchain-rpc-endpoint can be left to its default value of an empty string.
Set blockchain RPC endpoint
Full and light Bee nodes require a Gnosis Chain RPC endpoint so they can interact with and deploy their chequebook contract, see the latest view of the current postage stamp batches, and interact with and top-up postage stamp batches. A blockchain RPC endpoint is not required for nodes running in ultra-light mode.
If you do not wish to run your own Gnosis Chain node and are willing to trust a third party, you may also consider using an RPC endpoint provider such as GetBlock.
For running a light node or for testing out a single full node you may also consider using one of the free public RPC endpoints listed in the Gnosis Chain documentation. However the providers of these endpoints make no SLA or availability guarantees, and is therefore not recommended for full node operators.
To set your RPC endpoint provider, specify it in configuration for the
blockchain-rpc-endpoint value, which is set to an empty string by default.
Configure Swap Initial Deposit (Optional)
When running your Bee node with SWAP enabled for the first time, your Bee node will deploy a 'chequebook' contract using the canonical factory contract which is deployed by Swarm. A factory is used to ensure every node is using legitimate and verifiable chequebook contracts. Once the chequebook is deployed, Bee will (optionally) deposit a certain amount of xBZZ in the chequebook contract so that it can pay other nodes in return for their services. The amount of xBZZ transferred to the chequebook is set by the
swap-initial-deposit configuration setting (it may be left at the default value of zero or commented out).
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 in order to 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).
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 a mainnet Ethereum blockchain node. We recommend you run your own ethereum node. An option for resource restricted devices is geth+nimbus and a guide can be found here. Other options include dappnode, nicenode, stereum and avado.
If you do not wish to run your own Ethereum node you may use a blockchain API service provider such as Infura. After signing up for Infura's API service, simply set your
3. Find Bee address
As part of the process of starting a Bee full node or light node the node must issue a Gnosis Chain transaction which is paid for using xDAI. We therefore need to find our node's Gnosis Chain address. We can find it by reading it directly from our key file:
sudo cat /var/lib/bee/keys/swarm.key
Output from cat /var/lib/bee/keys/swarm.key:
address field contains the Gnosis Chain address of the node, simply add the
Do not share the contents of your
swarm.key or any other keys with anyone, this example is for a throwaway account.
4. Fund Node
We recommend not holding a high value of xBZZ or xDAI in your nodes' wallet. Please consider regularly removing accumulated funds.
Before funding your node, you first need to get some xDAI. You can send it either from your own Gnosis Chain compatible wallet such as Metamask, or from a centralized exchange which supports xDAI withdrawals to Gnosis Chain. If you already have some DAI on Ethereum, you can use the xDAI bridge to mint xDAI on Gnosis Chain.
Once you have some xDAI ready, you're ready to fund your Bee node. Send at least 1 xDAI to the address you found in the previous step to fund your node. You can optionally also send some xBZZ to your node which you can use to pay for storage on Swarm.
While depositing xBZZ is optional, node operators who intend to download or upload large amounts of data on Swarm may wish to deposit some xBZZ in order to pay for SWAP settlements. See the section on node funding for more information.
For nodes which stake xBZZ and participate in the storage incentives system, very small amounts of xDAI will be used regularly to pay for staking related transactions on Gnosis Chain, so xDAI may need to be periodically topped up. See the staking section for more information.
After sending xDAI and optionally xBZZ to the Gnosis Chain address collected in the previous step, restart the node:
5. Wait for Initialisation
When first started in full or light mode, 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.
If all goes well, you will see your node automatically begin to connect to other Bee nodes all over the world.
INFO[2020-08-29T11:55:16Z] greeting <Hi I am a very buzzy bee bzzzz bzzz bzz. 🐝> from peer: b6ae5b22d4dc93ce5ee46a9799ef5975d436eb63a4b085bfc104fcdcbda3b82c
Now your node will begin to request chunks of data that fall within your radius of responsibilty - data that you will then serve to other p2p clients running in the swarm. Your node will then begin to respond to requests for these chunks from other peers.
In Swarm, storing, serving and forwarding chunks of data to other nodes can earn you rewards! Follow this guide to learn how to regularly cash out cheques other nodes send you in return for your services so that you can get your xBZZ!
Your Bee client has now generated an elliptic curve key pair similar to an Ethereum wallet. These are stored in your data directory, in the
Your keys and password are very important, back up these files and store them in a secure place that only you have access to. With great privacy comes great responsibility - while no-one will ever be able to guess your key - you will not be able to recover them if you lose them either, so be sure to look after them well and keep secure backups.
6. Check if Bee is Working
First check that the correct version of Bee is installed:
Once the Bee node has been funded, the chequebook deployed, and postage stamp
batch store synced, its HTTP API
will start listening at
To check everything is working as expected, send a GET request to localhost port 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. Note that the debug api listens at port 1635 by default (
Here we are using the
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"
Welcome to the swarm! 🐝 🐝 🐝 🐝 🐝
7. Back Up Keys
Once your node is up and running, make sure to back up your keys.
8. Deposit Stake (Optional)
While depositing stake is not required to run a Bee node, it is required in order for a node to receive rewards for sharing storage with the network. You will need to deposit xBZZ to the staking contract for your node. To do this, send a minimum of 10 xBZZ to your nodes' wallet and run:
curl -XPOST localhost:1635/stake/100000000000000000
This will initiate a transaction on-chain which deposits the specified amount of xBZZ into the staking contract.
Storage incentive rewards are only available for full nodes which are providing storage capacity to the network.
Note that SWAP rewards are available to all full and light nodes, regardless of whether or not they stake xBZZ in order to participate in the storage incentives system.
The CLI has documentation built-in. Running
bee gives you an entry point to the documentation. Running
bee start -h or
bee start --help will tell you how you can configure your Bee node via the command line arguments.
You may also check out the configuration guide, or simply run your Bee terminal command with the
--help flag, eg.
bee start --help or
Next Steps to Consider
Access the Swarm
If you'd like to start uploading or downloading files to Swarm, start here.
Explore the API
The Bee API and Debug API are the primary methods for interacting with Bee and getting information about Bee. After installing Bee and getting it up and running, it's a good idea to start getting familiar with the APIs.
Run a hive!
If you would like to run a hive of many Bees, check out the hive operators section for information on how to operate and monitor many Bees at once.
Start building DAPPs on Swarm
If you would like to start building decentralised applications on Swarm, check out our section for developing with Bee.