Skip to main content


Bee is a very flexible piece of software, and can be configured in a variety of ways depending on your use case. This expanded section will cover configuration in detail.

Important Configuration Changes#


Before starting Bee for the first time, there is some configuration to do! Make sure you consider updating the recommended settings in the installation guide!

Specifying Configuration#

Configuration Priority#

Configuration is processed in the following ascending order of preference:

  1. Command Line Arguments
  2. Environment Variables
  3. Configuration File

Command Line Arguments#

Run bee start --help in your Terminal to get the list of available command line arguments.

Environment variables#

Bee config may also be passed using environment variables.

Environment variables are set as variables in your operating system's session or systemd configuration file. To set an environment variable, type the following in your terminal session.

export VARIABLE_NAME=variableValue

Verify if it is correctly set by running echo $VARIABLE_NAME.

All available configuration options are available as BEE prefixed, capitalised, and underscored environment variables.

e.g. --api-addr becomes BEE_API_ADDR.

Configuration file#

Bee can also be configured by providing a YAML configuration file using the --config flag.

bee start --config /home/<user>/bee-config.yaml

Automatically generate a config file#

Configuration files can be easily generated by simply substituting the start command with printconfig when starting Bee using the command line.

bee printconfig &> bee-config.yaml

This produces the following file contents, showing the default configuration of Bee:

admin-password: ""
allow-private-cidrs: false
api-addr: :1633
block-hash: ""
block-time: "15"
bootnode: []
bootnode-mode: false
cache-capacity: "1000000"
cache-retrieval: true
chain-enable: true
chequebook-enable: true
clef-signer-enable: false
clef-signer-endpoint: ""
clef-signer-ethereum-address: ""
config: /root/.bee.yaml
cors-allowed-origins: []
data-dir: /root/.bee
db-block-cache-capacity: "33554432"
db-disable-seeks-compaction: false
db-open-files-limit: "200"
db-write-buffer-size: "33554432"
debug-api-addr: :1635
debug-api-enable: false
full-node: false
gateway-mode: false
help: false
mainnet: true
nat-addr: ""
network-id: "10"
p2p-addr: :1634
p2p-ws-enable: false
password: ""
password-file: ""
payment-early-percent: 50
payment-threshold: "100000000"
payment-tolerance-percent: 25
postage-stamp-address: ""
pprof-mutex: false
pprof-profile: false
price-oracle-address: ""
resolver-options: []
restricted: false
resync: false
static-nodes: []
swap-deployment-gas-price: ""
swap-enable: true
swap-endpoint: ws://localhost:8546
swap-factory-address: ""
swap-initial-deposit: "10000000000000000"
swap-legacy-factory-addresses: []
token-encryption-key: ""
tracing-enable: false
tracing-host: ""
tracing-port: ""
tracing-service-name: bee
transaction: ""
use-postage-snapshot: false
verbosity: info
warmup-time: 20m0s
welcome-message: ""

Configuring Bee Installed Using a Package Manager#

Bee node's installed using package managers apt-get or yum are configured using a configuration file which is automatically generated during the installation process.

To alter Bee's configuration, simply edit the configuration file as desired, and restart your Bee service.


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


vi /usr/local/etc/swarm-bee/bee.yaml
brew services restart swarm-bee

Configuration Options#

Bee provides the following options to customise your node.



default /home/<user>/.bee.yaml

The location of a YAML configuration file containing configuration options. See configuration.



When the permission checks for the API is enabled then this option configure admin password that is used to generate Bearer tokens.

Be aware that you need to pass a bcrypt hash of the password here not the actual plaintext password!

default ""

--allow-private-cidrs: false#

default ""


default :1633

The IP and port the API will serve HTTP requests from. Omitting the IP part of the address will cause the server to listen to all interfaces. Argument values are of the form ''.


default 15

The expected block time of the attached SWAP endpoint.


default ""

The block hash of the block whose parent is the block that contains the transaction hash


default /dnsaddr/

This is a multiaddr specifying the Bee bootnodes used for bootstrapping the network. It can be multiple values.

By default a node connects to the Swarm mainnet. When using a private or test network, network specific bootnodes must be set.

Any Bee node in a network can act as a bootnode.


default false

Cause the node to always accept incoming connections


default 1000000

The amount of disk space, in chunks, that is used for forwarding and uploading chunks.


default true

Enable the caching of forwarded content.


default true

Use a blockchain backend, and hence participate in protocols requiring one.


default true

Enable chequebook.


default false

Set this to true to enable signing using Ethereum's Clef external signer. Clef is a new feature which requires a corresponding rules files or running in advanced mode to allow for auto-signing of handshakes and cheques.


default default path for clef for each host operating system

You may also specify a custom IPC file path for your Clef signer.


default selects the clef address at index 0

Use this command to specify which Bee Clef address is used if you have imported multiple keys into Bee Clef.


If you have multiple addresses imported into your instance of Bee Clef, you must specify your address for each node, including the first one, as addresses may been re-ordered during import.


default []

HTTP/WS origin domains or wildcards defining these, which the API will allow responses to, e.g.

bee start --cors-allowed-origins="*"
bee start --cors-allowed-origins=""


default /home/<user>/.bee

The location on your disk where Bee stores its data. Data in this directory will be required to restore a node state using the same key.

This consists of the following three types of data.

1. Chunk Data (localstore)#

This consists of chunks and files that you have pinned locally, cached chunks you have requested, or chunks within your radius of responsibility which you are responsible for serving to your peers.

2. State Data (statestore)#

This is information about the local state of your Bee node and should be backed up.

3. Keystore Data (keys)#

These files contain encrypted versions of your private key and should be backed up and kept private.


Keep the key files in your keystore data directory safe!

They are the cryptographic proof of your network identity and cannot be recovered.

The next four options expose low-level configurations for LevelDB's  Openfile method. Please let us know how you get on with tweaking these settings on your hardware in the #node-operators channel on our Discord server


default 33554432

Corresponds to LevelDB BlockCacheCapacity (see above)


default false

Corresponds to LevelDB DisableSeeksCompaction (see above)


default 200


To accomodate less powerful hardware and operating systems, the db-open-files-limit is set deliberately low. We recommend that you try to increase it to nearer to 10000 or more if this is possible when using your hardware. Please let us know how you get on with tweaking these settings on your hardware in the #node-operators channel on our Discord server

Corresponds to LevelDB OpenFilesCacheCapacity (see above)


default 33554432

Corresponds to LevelDB WriteBuffer (see above)


default :1635

The IP and port the Debug API will serve HTTP requests from.

Omitting the IP part of the address will cause the server to listen to all requests.

--debug-api-enable must be set to true.


default false

Set this to true to enable access to the Debug API


default false

Enable this by setting it to true to fully participate in serving and forwarding chunks to the network.


default false

Set this to true to disable a set of sensitive features in the API to ensure that it is safe to expose your api-addr to the public Internet.


default false

Set to true to connect to Swarm mainnet.


default ""

Sets the expected public IP. Normally this is generated automatically, but in certain circumstances it may be desirable to set it manually.

Format is where the port number is your Bee p2p port.


default 1 if --mainnet=true default 10 if --mainnet=false

The network ID for which to accept new connections. Set to 1 for mainnet, 10 for testnet.


default :1634

The IP and port to listen for p2p protocol messages.


default false

Enables web-sockets transport for p2p communications.


default ""

Password used to decrypt Swarm identity keys.


Passing passwords as command line arguments is insecure. Use a password file or environment variable in production environments.


default ""

The path to a file that contains password for decrypting keys. The empty string assumes no file is presented.


default 50

Percentage below the peers payment threshold when we initiate settlement.


default 100000000

The threshold in BZZ where you expect to get paid from your peers.


default 25

Excess debt above payment threshold as a percentage where you disconnect from your peer (default 25).


default automatically configured depending on network

The address of the postage stamp contract on the Ethereum blockchain, used for buying batches of stamps.


default eth:0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e@localhost:8545

ENS API endpoint for a TLD, with contract address. Multiple values can be provided.

Settings should be provided in the format [tld:][contract-addr@]url

A default top level domain and resolver contract address are provided, but an ENS/Geth endpoint must be provided to enable this functionality.


default false

Enable permission check on certain http APIs. More information how to restrict the access to the APIs is available here.

If enabled - you must specify an admin password using the --admin-password option and a --token-encryption-key string value.

To generate a valid admin password use the provided bcrypt utility


default false

Forces the node to resync postage contract data.


default []

Protect nodes from getting kicked out on bootnode


default determined automatically

Gas price in wei to use for deployment and funding


default true


default ws://localhost:8546

SWAP Gnosis Chain (mainnet) or Goerli (testnet) blockchain endpoint.


default anointed contract for the current blockchain id


default 10000000000000000



Admin username to get the security token.


default false

Send tracing spans to the tracing service. More information how to configure and visualize tracing data is available here.



The URL where the tracing service listens for Thrift protocol UDP messages.


default ""

Host to send tracing data.


default ""

Port to send tracing data.


default bee

Bee service identifier in tracing spans.


default ""

As a spam prevention measure, for nodes which deployed their chequebook with v0.5.0 or before, specify transaction - the transaction hash of any Ethereum transaction on the XDAI network sent from the Bee node's Ethereum address.


default info

0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace


default 20m0s

Time to warmup the node before pull/push protocols can be kicked off.


default ""

Custom welcome message to be displayed to peers on succesful connection.