Setup & Run

Viewing command help

You can check that your binaries are properly compiled with:

./nym-client --help

Console output

Implementation of the Nym Client

Usage: nym-client [OPTIONS] <COMMAND>

  init               Initialise a Nym client. Do this first!
  run                Run the Nym client with provided configuration client optionally overriding
                         set parameters
  build-info         Show build information of this binary
  completions        Generate shell completions
  generate-fig-spec  Generate Fig specification
  help               Print this message or the help of the given subcommand(s)

  -c, --config-env-file <CONFIG_ENV_FILE>  Path pointing to an env file that configures the client
      --no-banner                          Flag used for disabling the printed banner in tty
  -h, --help                               Print help
  -V, --version                            Print version

The two most important commands you will issue to the client are:

  • init - initalise a new client instance.
  • run - run a mixnet client process.

You can check the necessary parameters for the available commands by running:

./nym-client <command> --help

Initialising your client

Before you can use the client, you need to initalise a new instance of it. Each instance of the client has its own public/private keypair, and connects to its own gateway node. Taken together, these 3 things (public/private keypair + gateway node identity key) make up an app’s identity.

Initialising a new client instance can be done with the following command:

./nym-client init --id example-client

Console output

 Version: 1.1.32
ID: example-client
Identity key: 6y1zv84EeJepQL7utxKKNtWhZBGsZ6bj5cRWWWqH48TP
Encryption: 6zPxwTfwW5FejkNUHthqd929PyYh2vCqnPfaKge5m5y7
Gateway ID: 8ShVhzs9fpKyZPgdtTTRT8yviU2tqk3i5Hnk7rMfLbML
Gateway: ws://
Client listening port: 1977
Address of this client: 6y1zv84EeJepQL7utxKKNtWhZBGsZ6bj5cRWWWqH48TP.6zPxwTfwW5FejkNUHthqd929PyYh2vCqnPfaKge5m5y7@8ShVhzs9fpKyZPgdtTTRT8yviU2tqk3i5Hnk7rMfLbML

The --id in the example above is a local identifier so that you can name your clients; it is never transmitted over the network.

There is an optional --gateway flag that you can use if you want to use a specific gateway. The supplied argument is the Identity Key of the gateway you wish to use, which can be found on the mainnet Network Explorer or Sandbox Testnet Explorer depending on which network you are on.

Not passing this argument will randomly select a gateway for your client.

Running your client

You can run the initalised client by doing this:

./nym-client run --id example-client

When you run the client, it immediately starts generating (fake) cover traffic and sending it to the mixnet.

When the client is first started, it will reach out to the Nym network’s validators, and get a list of available Nym nodes (gateways, mixnodes, and validators). We call this list of nodes the network topology. The client does this so that it knows how to connect, register itself with the network, and know which mixnodes it can route Sphinx packets through.

Last change: 2023-12-04, commit: caf055e