Your Bee node can be configured by adding arguments terminal command on startup.

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


In this example, we change the port that the Bee API runs on, enable the Debug API, and set it to listen on port 6666.

bee start \
--api-addr=:8888 \
--debug-api-enable=true \

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

Run bee printconfig &> bee-default.yaml to print a default version of the configuration file.

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 node using systemctl.


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


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

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.


Here we substitute start for printconfig when specifying arguments at the command line.

bee printconfig \
--verbosity=5 \
&> bee-config.yaml

This produces the following file contents, showing the default configuration of Bee, with some added log verbosity:

api-addr: :1633
- /dnsaddr/
clef-signer-enable: false
clef-signer-endpoint: ""
cors-allowed-origins: []
data-dir: /Users/sig/.bee
db-capacity: "5000000"
debug-api-addr: :1635
debug-api-enable: false
gateway-mode: false
global-pinning-enable: false
nat-addr: ""
network-id: "1"
p2p-addr: :1634
p2p-quic-enable: false
p2p-ws-enable: false
password: ""
password-file: ""
payment-early: "10000"
payment-threshold: "100000"
payment-tolerance: "10000"
resolver-options: []
standalone: false
swap-enable: true
swap-endpoint: http://localhost:8545
swap-factory-address: ""
swap-initial-deposit: "100000000"
tracing-enable: false
tracing-service-name: bee
verbosity: info
welcome-message: ""

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 instructions. See configuration.



default :1633

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


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

Set this to true to enable signing using Ethereum's 'Clef' external signer. Clef is an 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 []

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 it's data. This consists of the following three types of data.

Data in this directory will be required to restore a node state using the same key.

1. Chunk Data

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

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

3. Keystore Data

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.


default 5000000

Chunk database capacity in chunks. A chunk is 4096 bytes in size, so the total database capacity in kb can be estimated as db-capacity * 4096. The default 5,000,000 chunks is therefore approximately 20.5gb. We recommend a minimum of 2.5gb capacity for a node to be able to effectively function in the network. Light nodes that do not participate in storing may be able to specify less.


default :1635

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

Ommiting 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

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

Enables the Global Pinning functionality when set to true.


default ""

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


default 1

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


default :1634

The ip and port to listen for p2p protocol messages.


default false


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.


Amount in BZZ below the peers payment threshold which causes Bee to initiate settlement (default 10000)


default 100000

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


default 10000

The excess debt above payment threshold in BZZ where you disconnect from your peer.


default eth:0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e

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

Set this flag if we would like the node not to try to connect to the network. Useful for development.


default true


default http://localhost:8545

SWAP ethereum blockchain endpoint.


default anointed contract for the current blockchain id


default 100000000


default false

Send tracing spans to the tracing service. More information how to configure and visualize tracing data is available on /docs/bee-developers/useful-dev-info#tracing.



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


default bee

Bee service identifier in tracing spans.


default info

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


default ""

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

Environment variables

Bee config may also be passed using environment variables.

Environment variables are set as variables in your operating systems 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 also available as prefixed, captilised and underscored environment variables.

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

Precedence Order of Configuration

Configuration is processed in the following ascending priority order of preference:

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