As a peer to peer system, every node running a Holochain app needs to be able to communicate over a network with other nodes. Creating a network connection between nodes can be a bit complex, so there are different approaches. 

There are three primary techniques involved in getting nodes to communicate, and these are adjustable via arguments that you can provide to the command line when you run commands. Holochain will attempt to make connections via all of the enabled techniques outlined below.

MDNS & Local Networks

The simplest is what's known as MDNS (multicast DNS). It is a protocol implemented on UNIX (mac and linux) devices that enables nodes on a network to identify one another, and subsequently, communicate. When your nodes (UNIX only) are all connected to the same Wifi network, or wired network, they will succeed in connecting and communicating (gossip-ing). Holochain (in developer mode) runs with MDNS enabled by default, so you don't have to run anything special to make it work. Just running the following will work.

$ hcdev web

If you wanted to disable MDNS for some reason, there is an --mdns argument you can pass.

$ hcdev --mdns=false web

NAT, UPNP, and Connections over the Internet

Home routers perform Network Address Translation (NAT) to make a single IP address behave like many, which makes it simple to make outgoing connections to the internet, but difficult to receive incoming connections from the internet, which we need to enable communication between Holochain nodes.

Holochain takes two different approaches to solving this.

One is NAT UPNP (Universal Plug and Play). Some routers support NAT UPNP (not all do), but Holochain will provide feedback if using UPNP fails. UPNP is off by default in developer mode (hcdev). To enable it, run the following command.

$ hcdev --upnp web

It will attempt to auto open a port for you if you are testing with other nodes on the web.

There is another technique we use, common in P2P networked applications, of signalling presence to one another via a 'signalling server', or what we call the 'Bootstrap' server, because it bootstraps nodes into connection.

Bootstrap Servers

There is an always on bootstrap server maintained by Holo, but in order to avoid centralization, it is also configurable, and others can run their own. The default bootstrap server is set to

By default at startup, nodes check in with our bootstrap server ( to find other nodes on the same Holochain app.

You can deactivate this by using the flag like the following

 $ hcdev --bootstrapServer=_ web

Additionally you can run your own bootstrap server. In its own terminal, just run

$ bs

This will start up your own bootstrap server. It comes packaged with the Holochain command lines tools.

When you run the server, it will give you a port number that it is running on, defaulting to 3142. So then localhost:3142 would be your bootstrap server. This could be passed to a local node to connect to. That could be done like the following

$ hcdev --bootstrapServer=localhost:3142 web

The bootstrap server conveniently provides a way to debug whether devices are connecting. To see a node list, all you need is the DNA hash for your app. Such as QmefscAq5AKScmhsRGNjavGGKK37UD8bkYMs9oZH25QLR7

To access the node list, view http://localhost:3142/QmefscAq5AKScmhsRGNjavGGKK37UD8bkYMs9oZH25QLR7

This will show something like the following.

31298 original

This is true for the default hosted bootstrap server as well, so to access a node list, just view