Skip to main content

Swarm Shell Script Installation Guide

The official shell script provided by Swarm automatically detects your system and installs the correct version of Bee. This installation method is an excellent choice if you're looking for a minimalistic and flexible option for your Bee node installation.

warning

Note that we append 127.0.0.1 (localhost) to our Bee API's port (1633 by default), since we do not want to expose our Bee API endpoint to the public internet, as that would allow anyone to control our node. Make sure you do the same. Additionally, it's recommended to use a firewall to restrict access to your node(s).

info

This guide uses command line flag options in the node startup commands such as --blockchain-rpc-endpoint, however, there are several other methods available for configuring options.

Install and Start Your Node​

Below is a step-by-step guide for installing and setting up your Bee node using the shell script installation method.

Run Shell Script​

Run the install shell script using either curl or wget:

caution

In the example below, the version is specified using TAG=v2.4.0. Check the latest Bee releases and if needed, update the command to install the most recent version (note that in tags containing "rc," the abbreviation stands for "release candidate", and these versions should be used for testing purposes only).

info

Note that while this shell script supports many commonly used Unix-like systems, it is not quite a universal installer tool. The architectures it supports include:

1. Linux:

  • linux-386 (32-bit x86)
  • linux-amd64 (64-bit x86)
  • linux-arm64 (64-bit ARM)
  • linux-armv6 (32-bit ARM v6)

2. macOS (Darwin):

  • darwin-arm64 (Apple Silicon, M1/M2/M3)
  • darwin-amd64 (Intel-based Mac)

This means the script works on most modern Linux distributions and macOS versions that match these architectures. Windows users can use WSL.

caution

You may need to install curl or wget if your system doesn't have one of them pre-installed and the shell script command fails to run.

curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.4.0 bash

Let's check that the script ran properly:

bee

If the script ran without any problems you should see this:

Ethereum Swarm Bee

Usage:
  bee [command]

Available Commands:
  start       Start a Swarm node
  dev         Start a Swarm node in development mode
  init        Initialise a Swarm node
  deploy      Deploy and fund the chequebook contract
  version     Print version number
  db          Perform basic DB related operations
  split       Split a file into chunks
  printconfig Print default or provided configuration in yaml format
  help        Help about any command
  completion  Generate the autocompletion script for the specified shell

Flags:
      --config string   config file (default is $HOME/.bee.yaml)
  -h, --help            help for bee

Use "bee [command] --help" for more information about a command.

Node Startup Commands​

Let's try starting up our node for the first time with the command below. Make sure to pick a strong password of your own:

Below are startup commands configured for each of the three Bee node types, full, light, and ultra-light. Refer to the Node Types page to learn more about each node type and decide which one best suits your needs.

For the full node, we have --full-node and --swap-enable both enabled, and we've used --blockchain-rpc-endpoint to set our RPC endpoint as https://xdai.fairdatasociety.org. Your RPC endpoint may differ depending on your setup.

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

Command explained:

  1. bee start: This is the command to start the Bee node.

  2. --password flummoxedgranitecarrot: The password to decrypt the private key associated with the node. Replace "flummoxedgranitecarrot" with your actual password.

  3. --full-node: This option enables the node to run in full mode, sharing its disk with the network, and becoming eligible for staking.

  4. --swap-enable: This flag enables SWAP, which is the bandwidth incentives scheme for Swarm. It will initiate a transaction to set up the SWAP chequebook on Gnosis Chain (required for light and full nodes).

  5. --api-addr 127.0.0.1:1633: Specifies that the Bee API will be accessible locally only via 127.0.0.1 on port 1633 and not accessible to the public.

  6. --blockchain-rpc-endpoint https://xdai.fairdatasociety.org: Sets the RPC endpoint for interacting with the Gnosis blockchain (required for light and full nodes).

Example Startup Output​

The node has successfully started, but it still needs funding with xDAI (for Gnosis Chain transactions) and xBZZ (for uploads, downloads, and staking).

Welcome to Swarm.... Bzzz Bzzzz Bzzzz
                \     /
            \    o ^ o    /
              \ (     ) /
   ____________(%%%%%%%)____________
  (     /   /  )%%%%%%%(  \   \     )
  (___/___/__/           \__\___\___)
     (     /  /(%%%%%%%)\  \     )
      (__/___/ (%%%%%%%) \___\__)
              /(       )\
            /   (%%%%%)   \
                 (%%%)
                   !

DISCLAIMER:
This software is provided to you "as is", use at your own risk and without warranties of any kind.
It is your responsibility to read and understand how Swarm works and the implications of running this software.
The usage of Bee involves various risks, including, but not limited to:
damage to hardware or loss of funds associated with the Ethereum account connected to your node.
No developers or entity involved will be liable for any claims and damages associated with your use,
inability to use, or your interaction with other nodes or the software.

version: 2.2.0-06a0aca7 - planned to be supported until 11 December 2024, please follow https://ethswarm.org/

"time"="2024-09-24 18:15:34.383102" "level"="info" "logger"="node" "msg"="bee version" "version"="2.2.0-06a0aca7"
"time"="2024-09-24 18:15:34.428546" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="0373fe2ab33ab836635fc35864cf708fa0f4a775c0cf76ca851551e7787b58d040"
"time"="2024-09-24 18:15:34.520686" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="03a341032724f1f9bb04f1d9b22607db485cccd74174331c701f3a6957d94d95c1"
"time"="2024-09-24 18:15:34.520716" "level"="info" "logger"="node" "msg"="using ethereum address" "address"="0x1A801dd3ec955E905ca424a85C3423599bfb0E66"
"time"="2024-09-24 18:15:34.533789" "level"="info" "logger"="node" "msg"="fetching target neighborhood from suggester" "url"="https://api.swarmscan.io/v1/network/neighborhoods/suggestion"
"time"="2024-09-24 18:15:36.773501" "level"="info" "logger"="node" "msg"="mining a new overlay address to target the selected neighborhood" "target"="00100010110"
"time"="2024-09-24 18:15:36.776550" "level"="info" "logger"="node" "msg"="using overlay address" "address"="22d502d022de0f8e9d477bc61144d0d842d9d82b8241568c6fe4e41f0b466615"
"time"="2024-09-24 18:15:36.776576" "level"="info" "logger"="node" "msg"="starting with an enabled chain backend"
"time"="2024-09-24 18:15:37.388997" "level"="info" "logger"="node" "msg"="connected to blockchain backend" "version"="erigon/2.60.7/linux-amd64/go1.21.5"
"time"="2024-09-24 18:15:37.577840" "level"="info" "logger"="node" "msg"="using chain with network network" "chain_id"=100 "network_id"=1
"time"="2024-09-24 18:15:37.593747" "level"="info" "logger"="node" "msg"="starting debug & api server" "address"="127.0.0.1:1633"
"time"="2024-09-24 18:15:37.969782" "level"="info" "logger"="node" "msg"="using default factory address" "chain_id"=100 "factory_address"="0xC2d5A532cf69AA9A1378737D8ccDEF884B6E7420"
"time"="2024-09-24 18:15:38.160249" "level"="info" "logger"="node/chequebook" "msg"="no chequebook found, deploying new one."
"time"="2024-09-24 18:15:38.728534" "level"="warning" "logger"="node/chequebook" "msg"="cannot continue until there is at least min xDAI (for Gas) available on address" "min_amount"="0.0003750000017" "address"="0x1A801dd3ec955E905ca424a85C3423599bfb0E66"

Fund and Stake​

Running a full node for the purpose of earning xBZZ by sharing disk space and participating in the redistribution game requires a minimum of 10 xBZZ and a small amount of xDAI (for initializing the chequebook contract and for paying for redistribution-related transactions).

While running a light node requires a small amount of xDAI to pay for initializing the chequebook contract and a smaller amount of xBZZ to pay for uploads and downloads.

Fund node​

Check the logs from the previous step. Look for the line which says:

"time"="2024-09-24 18:15:34.520716" "level"="info" "logger"="node" "msg"="using ethereum address" "address"="0x1A801dd3ec955E905ca424a85C3423599bfb0E66"

That address is your node's address on Gnosis Chain which needs to be funded with xDAI (and also xBZZ if you plan on doing any uploading or on staking). Copy it and save it for the next step.

You can also use the following command:

curl -s localhost:1633/addresses | jq .ethereum

Which will return your node's address:

"0x1A801dd3ec955E905ca424a85C3423599bfb0E66"

How Much to Send?

Only a very small amount of xDAI is needed to get started, 0.1 xDAI is more than enough.

For very small short term uploads you can start with ~0.2 xBZZ, but the required amount will scale up with the volume and duration of storage required.

You will also need at least 10 xBZZ if you plan on staking.

Initialize full node​

After sending the required tokens of ~0.1 xDAI and 10 xBZZ (or a smaller amount of xBZZ if you don't plan on staking) to your node's Gnosis Chain address, close the bee process in your terminal (Ctrl + C). Then start it again with the same command:

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

After funding and restarting your node, the logs printed to the terminal should look something like this:

Welcome to Swarm.... Bzzz Bzzzz Bzzzz
                \     /
            \    o ^ o    /
              \ (     ) /
   ____________(%%%%%%%)____________
  (     /   /  )%%%%%%%(  \   \     )
  (___/___/__/           \__\___\___)
     (     /  /(%%%%%%%)\  \     )
      (__/___/ (%%%%%%%) \___\__)
              /(       )\
            /   (%%%%%)   \
                 (%%%)
                   !

DISCLAIMER:
This software is provided to you "as is", use at your own risk and without warranties of any kind.
It is your responsibility to read and understand how Swarm works and the implications of running this software.
The usage of Bee involves various risks, including, but not limited to:
damage to hardware or loss of funds associated with the Ethereum account connected to your node.
No developers or entity involved will be liable for any claims and damages associated with your use,
inability to use, or your interaction with other nodes or the software.

version: 2.2.0-06a0aca7 - planned to be supported until 11 December 2024, please follow https://ethswarm.org/

"time"="2024-09-24 18:57:16.710417" "level"="info" "logger"="node" "msg"="bee version" "version"="2.2.0-06a0aca7"
"time"="2024-09-24 18:57:16.760154" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="0373fe2ab33ab836635fc35864cf708fa0f4a775c0cf76ca851551e7787b58d040"
"time"="2024-09-24 18:57:16.854594" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="03a341032724f1f9bb04f1d9b22607db485cccd74174331c701f3a6957d94d95c1"
"time"="2024-09-24 18:57:16.854651" "level"="info" "logger"="node" "msg"="using ethereum address" "address"="0x1A801dd3ec955E905ca424a85C3423599bfb0E66"
"time"="2024-09-24 18:57:16.866697" "level"="info" "logger"="node" "msg"="using overlay address" "address"="22d502d022de0f8e9d477bc61144d0d842d9d82b8241568c6fe4e41f0b466615"
"time"="2024-09-24 18:57:16.866730" "level"="info" "logger"="node" "msg"="starting with an enabled chain backend"
"time"="2024-09-24 18:57:17.485408" "level"="info" "logger"="node" "msg"="connected to blockchain backend" "version"="erigon/2.60.1/linux-amd64/go1.21.5"
"time"="2024-09-24 18:57:17.672282" "level"="info" "logger"="node" "msg"="using chain with network network" "chain_id"=100 "network_id"=1
"time"="2024-09-24 18:57:17.686479" "level"="info" "logger"="node" "msg"="starting debug & api server" "address"="127.0.0.1:1633"
"time"="2024-09-24 18:57:18.065029" "level"="info" "logger"="node" "msg"="using default factory address" "chain_id"=100 "factory_address"="0xC2d5A532cf69AA9A1378737D8ccDEF884B6E7420"
"time"="2024-09-24 18:57:18.252410" "level"="info" "logger"="node/chequebook" "msg"="no chequebook found, deploying new one."
"time"="2024-09-24 18:57:19.576100" "level"="info" "logger"="node/chequebook" "msg"="deploying new chequebook" "tx"="0xf7bc9c5b04e96954c7f70cecfe717cad9cdc5d64b6ec080b2cbe712166ce262a"
"time"="2024-09-24 18:57:27.619377" "level"="info" "logger"="node/transaction" "msg"="pending transaction confirmed" "sender_address"="0x1A801dd3ec955E905ca424a85C3423599bfb0E66" "tx"="0xf7bc9c5b04e96954c7f70cecfe717cad9cdc5d64b6ec080b2cbe712166ce262a"
"time"="2024-09-24 18:57:27.619437" "level"="info" "logger"="node/chequebook" "msg"="chequebook deployed" "chequebook_address"="0x261a07a63dC1e7200d51106155C8929b432181fb"

Here we can see that after our node has been funded, it was able to issue the transactions for deploying the chequebook contract, which is a prerequisite for running a staking node.

Next your node will begin to sync postage stamp data, which can take ~5 to 10 minutes. You will see this log message while your node is syncing postage stamp data:

"time"="2024-09-24 22:21:19.664897" "level"="info" "logger"="node" "msg"="waiting to sync postage contract data, this may take a while... more info available in Debug loglevel"

After your node finishes syncing postage stamp data it will start in full node mode and begin to sync all the chunks of data it is responsible for storing as a full node:

"time"="2024-09-24 22:30:19.154067" "level"="info" "logger"="node" "msg"="starting in full mode"
"time"="2024-09-24 22:30:19.155320" "level"="info" "logger"="node/multiresolver" "msg"="name resolver: no name resolution service provided"
"time"="2024-09-24 22:30:19.341032" "level"="info" "logger"="node/storageincentives" "msg"="entered new phase" "phase"="reveal" "round"=237974 "block"=36172090
"time"="2024-09-24 22:30:33.610825" "level"="info" "logger"="node/kademlia" "msg"="disconnected peer" "peer_address"="6ceb30c7afc11716f866d19b7eeda9836757031ed056b61961e949f6e705b49e"

This process can take a while, even up to several hours depending on your system and network. You can check the progress of your node through the logs which print out to the Bee API:

You check your node's progress with the /status endpoint:

info

The jq utility jq utility formats API responses for easier reading:

  • Install it using your system’s package manager.
  • If you don't want to use it, remove | jq from all commands.
curl -s  http://localhost:1633/status | jq
{
  "overlay": "22dc155fe072e131449ec7ea2f77de16f4735f06257ebaa5daf2fdcf14267fd9",
  "proximity": 256,
  "beeMode": "full",
  "reserveSize": 686217,
  "reserveSizeWithinRadius": 321888,
  "pullsyncRate": 497.8747754074074,
  "storageRadius": 11,
  "connectedPeers": 148,
  "neighborhoodSize": 4,
  "batchCommitment": 74510761984,
  "isReachable": false,
  "lastSyncedBlock": 36172390
}

We can see that our node has not yet finished syncing chunks since the pullsyncRate is around 497 chunks per second. Once the node is fully synced, this value will go to zero. However, we do not need to wait until our node is fully synced in order to stake our node, so we can now move immediately to the next step.

Stake node​

Now we're ready to stake. We'll slightly modify our startup command so that it runs in the background instead of taking control of our terminal:

nohup bee start \
  --password flummoxedgranitecarrot \
  --full-node \
  --swap-enable \
  --api-addr 127.0.0.1:1633 \
  --blockchain-rpc-endpoint https://xdai.fairdatasociety.org > bee.log 2>&1 &
info

  1. nohup: nohup prevents the bee start process from stopping when the terminal closes.

  2. > bee.log 2>&1: Redirects both standard output and standard error to a log file called bee.log.

  3. &: This sends the process to the background, allowing the terminal to be used for other commands while the Bee node continues running.

Let's check the Bee API to confirm the node is running:

curl localhost:1633

If the node is running we should see:

Ethereum Swarm Bee

Now with our node properly running in the background, we're ready to stake our node. You can use the following command to stake 10 xBZZ:

curl -XPOST localhost:1633/stake/100000000000000000

If the staking transaction is successful a txHash will be returned:

{"txHash":"0x258d64720fe7abade794f14ef3261534ff823ef3e2e0011c431c31aea75c2dd5"}

We can also confirm that our node has been staked with the /stake endpoint:

curl localhost:1633/stake

The results will be displayed in PLUR units (1 PLUR is equal to 1e-16 xBZZ). If you have properly staked the minimum 10 xBZZ, you should see the output below:

{"stakedAmount":"100000000000000000"}

Congratulations! You have now installed your Bee node and are connected to the network as a full staking node. Your node will now be in the process of syncing chunks from the network. Once the node is fully synced, your node will finally be eligible to earn staking rewards.

Set Target Neighborhood​

When installing your Bee node it will automatically be assigned a neighborhood. However, when running a full node with staking there are benefits to periodically updating your node's neighborhood. Learn more about why and how to set your node's target neighborhood here.

Logs and monitoring​

info

You can learn more about Bee logs here.

With our previously modified command, our Bee node will now be running in the background and the logs will be written to the bee.log file. To review our node's logs we can simply view the file contents:

cat bee.log

The file will continue to update with all the latest logs as they are output:

"time"="2024-09-27 18:05:34.096641" "level"="info" "logger"="node/kademlia" "msg"="connected to peer" "peer_address"="03b48e678938d63c0761c74a805fbe0446684c9c417330c2bec600ecfd6c492f" "proximity_order"=8
"time"="2024-09-27 18:05:35.168425" "level"="info" "logger"="node/kademlia" "msg"="connected to peer" "peer_address"="0e9388fff473a9c74535337c32cc74d8f921514d2635d0c4a49c6e8022f5594e" "proximity_order"=4
"time"="2024-09-27 18:05:35.532723" "level"="info" "logger"="node/kademlia" "msg"="disconnected peer" "peer_address"="3c195cd8882ee537d170e92d959ad6bd72a76a50097a671c72646e83b45a1832"

There are many different ways to monitor your Bee node's process, but one convenient way to do so is the bashtop command line tool. The method of installation will vary depending on your system.

After installation, we can launch it with the bashtop command:

bashtop

We can use the f key to filter for our Bee node's specific process by searching for the bee keyword (use the arrow keys to navigate and enter to select). From here we can view info about our node's process, or shut it down using the t key (for "terminate").

Checking the Node's status with the Bee API

To check your node's status as a staking node, we can use the /redistributionstate endpoint:

curl -s http://localhost:1633/redistributionstate | jq

Below is the output for a node that has been running for several days:

{
  "minimumGasFunds": "11080889201250000",
  "hasSufficientFunds": true,
  "isFrozen": false,
  "isFullySynced": true,
  "phase": "claim",
  "round": 212859,
  "lastWonRound": 207391,
  "lastPlayedRound": 210941,
  "lastFrozenRound": 210942,
  "lastSelectedRound": 212553,
  "lastSampleDuration": 491687776653,
  "block": 32354719,
  "reward": "1804537795127017472",
  "fees": "592679945236926714",
  "isHealthy": true
}

For a complete breakdown of this output, check out this section in the Bee docs.

You can read more other important endpoints for monitoring your Bee node in the official Bee docs, and you can find complete information about all available endpoints in the API reference docs.

Back Up Keys​

Once your node is up and running, make sure to back up your keys.

Getting help​

The CLI has built-in documentation. 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 bee --help.

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 is the primary method 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 API.

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.