Running a local mixnet

Running a local mixnet for development

If you want to do mixnet development without connecting to our testnet, sometimes it’s convenient to run a full Nym network on your own machine.

You can start up a full mix network, including mixnodes, and a gateway on your local machine fairly easily.

First, download, build and run the Nym directory server. This step will soon go away, as the directory server is about to be retired in the 0.8.0 release. But for now it’s necessary.

The local network must be able to access a directory server running on localhost! Make sure you install and run the directory server.

Once you have a directory server running on port 8080, you can run the local network startup script:


By default, this will start up a 1x3 mixnet: a layered topology 1 mixnode wide and 3 layers deep, with a single gateway. At present, no validators are started.

You should see presence requests (a series of POST requests) hitting the directory server in its console window, telling you that (a) the directory server is receiving requests, and (b) the mixnodes are letting the directory know they’re alive.

Starting a Nym client will cause Sphinx packets to travel from the client to the gateway, and get routed to their Nym destination address.

client => Gateway => Mixnode1 => Mixnode2 => Mixnode3 => Gateway => loop back to the client

It’s also possible to run a larger number of mixnodes in your local mixnet:

./scripts/ 6

This will run a 2x3 mixnet: a layered topology 2 mixnodes wide and 3 layers deep, again with a single gateway.

                        1         2          3
                /=> Mixnode1 -> Mixnode3 -> Mixnode5 \
client => Gateway           X           X             => Gateway => client
                \=> Mixnode2 -> Mixnode4 -> Mixnode6 /

Packets always travel forwards through mixnet layers, and layers cannot be skipped. E.g.

  • the Peapp client sends only to its Gateway
  • Gateway sends to Mixnodes{1,2} (layer 1)
  • Mixnodes {1,2} send only to Mixnodes {3,4} (layer 2)
  • Mixnodes {3,4} send only to Mixnodes {5,6} (layer 3)
  • Mixnodes {5,6} send only to the Gateway(s).
  • Peap client gets messages from its Gateway

From here, you can start experimenting with running the nym-client, sending packets through the mixnet.

Init the client:

./target/release/nym-client init --id winston-smithnode --directory http://localhost:8080

Then run it:

./target/release/nym-client run --id winston-smithnode

For more info on developing with a running client, see the client documentation