Skip to main content

Setup a bootstrap node

You need to setup an additional edge device as a bootstrap node if mDNS is disabled on your devices or network, or if you are running ActyxOS on Docker.

Instead of automatically finding other nodes via mDNS, your node will now first connect to the bootstrap node, get a list of all nodes in your swarm from the bootstrap node, and then connect to them.


We advise to always use bootstrap nodes in production deployments to make sure all your nodes connect to each other.

Setup a bootstrap node#

Any physical or virtual edge device in your local network can serve as a bootstrap node.

The ActyxOS bootstrap node is publicly available on Docker Hub. You can download and run an ActyxOS bootstrap node with the following command:

# Start the bootstrap node with your swarm key
docker run --name actyxos_bootstrap_node --rm --env SWARM_KEY=L2tleS9zd2FybS9wc2svMS4wLjAvCi9iYXNlMTYvCjRkNWEzODQ3NGY1MjYzNDc1MjY2NTY3NTMwNTM0NjRkNGUzNzUyNDQ3ODY1NjIzMzRhMzg3MDU4NjU2MTcxNGQ= -p 4001:4001 -v actyxos-bootstrap-data:/data actyx/actyxos-bootstrap-node
Starting ActyxOS bootstrap node
ActyxOS bootstrap node running
bootstrap node address: /ip4/<YOUR_IP>/tcp/4001/ipfs/QmQ3iynxmtZUSNF5dvzQQEYhqnB4sqySRej3A2FgiAMBMH
Set the bootstrap node address using the `ax settings set` command on your
ActyxOS nodes (see for
more information). Replace <YOUR_IP> above with the IP address of this host.
Press Ctrl+C twice to shutdown this bootstrap node.
Run the bootstrap node with a persistent volume

It is highly recommended to use a persistent volume, as you will otherwise have to change the settings of all your ActyxOS nodes in this swarm each time you start the bootstrap node. If you want the node's identity to be preserved between runs, you need add a persistent volume with -v for storage of the node's identity. If you do so, the SWARM_KEY environment variable will be ignored in subsequent runs.

Configure your nodes to connect to the bootstrap node#

Now that your bootstrap node is running, you can configure nodes in your swarm with it:

The swarm key is a node setting. You can use the output from above and ax settings set to configure it:

ax settings set --local com.actyx.os/general/bootstrapNodes [/ip4/] localhost