nym/documentation/docs/pages/operators/nodes/nym-node/setup.mdx

import { Callout } from 'nextra/components';
import { Tabs } from 'nextra/components';
import { RunTabs } from 'components/operators/nodes/node-run-command-tabs';
import { VarInfo } from 'components/variable-info.tsx';
import { MigrateTabs } from 'components/operators/nodes/node-migrate-command-tabs';
import BuildInfo from 'components/outputs/command-outputs/nym-node-build-info.md';
import NymNodeHelp from 'components/outputs/command-outputs/nym-node-help.md';
import NymNodeRunHelp from 'components/outputs/command-outputs/nym-node-run-help.md';
import { AccordionTemplate } from 'components/accordion-template.tsx';
import TermsConditions from 'components/operators/snippets/tc-info.mdx';
import QuickStart from 'components/operators/snippets/quick-start.mdx'

# Nym Node Setup & Run

This documentation page provides a guide on how to set up and run a [NYM NODE](../nym-node.mdx), along with explanations of available flags, commands, and examples.

<VarInfo/ >

## Current version

```sh
nym-node
Binary Name:        nym-node
Build Timestamp:    2026-06-08T15:46:08.599178376Z
Build Version:      1.33.0
Commit SHA:         34709e76a1c23ed9f2f01bbb4f851fc44bfd7c8d
Commit Date:        2026-06-08T16:30:10.000000000+02:00
Commit Branch:      HEAD
rustc Version:      1.91.1
rustc Channel:      stable
cargo Profile:      release
```

Detailed version archive and release notes is documented [here](../../changelog.mdx).

{/* COMMENTING THIS OUT ASS WE HAVE TO FIGURE OUT HOW TO SHOW THE LATEST VERSION FROM MASTER BRANCH
<BuildInfo />
*/}


## Functionality (mode)

<Callout type="info">
From `nym-node v1.3.0` operators can choose multiple functionalities for their `nym-node` binary (flagged as `--mode`).

**However, the clients are yet to be developed to be able to make a proper selection for multi-mode nodes and therefore we ask operators to assign only one functionality to `--mode` option at a time. Please chose out of: `mixnode` or `entry-gateway` or `exit-gateway`. Chosing multiple at once will make your node non-routable!**
</Callout>

### Mixnet Routing

***Mixnet mode (5-hop) is the full anonymising option of NymVPN. Read more about the Mixnet architecture [here](/network/overview)***

Nym Node has three functionalities in the Mixnet: `entry-gateway`, `mixnode` and `exit-gateway`. These are selected with a flag `--mode <MODE>` alongside `nym-node` command `run` .

- **Entry Gateway (`--mode entry-gateway`)**: A node to which clients connect. It checks the bandwidth allowance, using [zk-nyms](../../../network/cryptography/zk-nym) and either sends [Sphinx packets](../../../network/cryptography/sphinx) through the mixnet or directly to Exit Gateway in case of dVPN (2-hop) routing. This node also receives replies and sends them back to users local client.

- **Mixnode (`--mode mixnode`)**: Nodes organized in three layers, randomly selected every epoch (60 minutes), mixing Sphinx packets, adding a slight latency to defend users agains time correlation attacks and sending them further to the next layer or to the Exit Gateway

- **Exit Gateway (`--mode exit-gateway`)**: The final node in the mixnet. It puts all packets together and using inbuilt Network requester and IP packet router, it sends traffic to the open internet. This node also recieves replies and sends them back to the user client.

<Callout type="warning">
Exit Gateway is the only mode routing data directly to the open internet. Therefore it exposes IP of operators server (VPS) to abuse complains. Before you decide to run an Exit Gateway, please read our [Community Counsel pages](../../community-counsel/exit-gateway) containing more information and some legal content.
</Callout>

### dVPN Routing

***dVPN routing (2-hop) is the Fast option of NymVPN. It runs a wireguard tunnel inside another wireguard tunnel. dVPN uses 2 Gateway layers (entry and exit) and no Mixnode layers. If an operator announces and [correctly configure](configuration#connectivity-test-and-configuration) their node to route wireguard, the node can be chosen as entry or exit by any client at any time.***

To activate wireguard routing, operators need to add `--wireguard-enabled true` alongside `nym-node` command `run`.

<Callout type="warning">
Wireguard nodes route data directly to the open internet. Therefore it exposes IP of operators server (VPS) to abuse complains. Before you decide to run a node with active wireguard routing, please read our [Community Counsel pages](../../community-counsel/exit-gateway) containing more information and some legal content.

**Wireguard mode has no exit policy right now - we are working on the implementation.**
</Callout>

Everything essential for each mode exists on `nym-node` by default. For instance, if you run a Mixnode, you'll find that a NR (Network Requester) and IPR (IP Packet Router) addresses exist, but they will be ignored in `mixnode` mode.

Note that every `exit-gateway` mode is basically an `entry-gateway` with NR (Network Requester) and IPR (IP Packet Router) enabled. This means that every `exit-gateway` can work as an `entry-gateway` but not the opposite.

<QuickStart />

## Command & Examples

**`nym-node` introduces a default human readible ID (local only) `default-nym-node`, which is used if there is not an explicit custom `--id <ID>` specified. All configuration is stored in `~/.nym/nym-nodes/default-nym-node/config/config.toml` or `~/.nym/nym-nodes/<ID>/config/config.toml` respectively.**

### Help Command

There are a few changes from the individual binaries used in the past. For example by default `run` command does initialisation function as well, local node `--id` will be set by default (1default-nym-node`) unless specified otherwise.

<Callout type="info" emoji="ℹ️">
You can always use `--help` flag to see the commands or arguments associated with a given command.
</Callout>

Run `./nym-node --help` to see all available commands:

<NymNodeHelp />

To list all available flags for each command, run `./nym-node <COMMAND> --help` for example `./nym-node run --help`:

<AccordionTemplate name="Command output">
<NymNodeRunHelp />
</AccordionTemplate>

<Callout type="warning" emoji="⚠️">
The Wireguard flags currently have limited functionality. From version `1.1.6` ([`v2024.9-topdeck`](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2024.9-topdeck)) wireguard is available and recommended to be switched on for nodes running as Gateways. Keep in mind that this option needs a bit of a special [configuration](configuration.md#wireguard-setup).
</Callout>

<TermsConditions />

Accepting T&Cs is done via a flag `--accept-operator-terms-and-conditions` added explicitly to `nym-node run` command every time. If you use [systemd](configuration.md#systemd) automation, add the flag to your service file's `ExecStart` line.

To check whether any node has T&Cs accepted or not can be done by querying Swagger API endpoint `/auxiliary_details` via one of these ports (depending on node setup):
```sh
# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
http://<NODE_IP_ADDRESS>:8080/api/v1/auxiliary_details
https://<NODE_DOMAIN>/api/v1/auxiliary_details
http://<NODE_IP_ADDRESS>/api/v1/auxiliary_details
```

```sh
# substitude <PUBLIC_IP> with a real one
curl -X 'GET' \
  'http://<NODE_IP_ADDRESS>:8080/api/v1/auxiliary-details' \
  -H 'accept: application/json'

{
  "location": "Kurdistan",
  "accepted_operator_terms_and_conditions": true
}
```

#### Essential Parameters & Variables

Running a `nym-node` in a `mixnode` mode requires less configuration than a full `exit-gateway` setup, we recommend operators to still follow through with all documented [configuration](configuration). Before you scroll down to syntax examples for the mode of your choice please familiarise yourself with the essential [paramters and variables](../../variables) convention we use in the guide.

<Callout>
To prevent over-flooding of our documentation we cannot provide with every single command syntax as there is a large combination of possibilities. Please read the [variables and parameters page](../../variables.mdx), use the explanation in `--help` option and common sence.
</Callout>


## Setup & Run

When we use `run` command for the first time the node will initialise all essential configuration and data files (unless specified with a flag `--deny-init`) stored at `$HOME/.nym/nym-nodes/<ID>` where the most important is the `config.toml` file stored at `$HOME/.nym/nym-nodes/<ID>/config/`. Below are some examples of initialising and running `nym-node` with different modes (`--mode`) like `mixnode`, `entry-gateway`, `exit-gateway`.

Please keep in mind that currently we ask operators to run only one functionality (`--mode`) at a time.

There is a simple default command to initialise and run your node: `./nym-node  run  --mode <MODE>`, however there quite a few parameters to be configured.

If an operator specifies any paramteres with optional flags alongside `run` command, these parameters passed in the option will take place over the ones in `config.toml` but they will not overwrite them by default. To overwrite them with the values passed with `run` command, a flag `-w` (`--write-changes`)  must be added.

Alternatively operators can just open a text editor and change these values manually. After saving the file,don't forget to restart the node or reload and restart the service. If all values are setup correctly in `config.toml`, then operator can use as simple command as `nym-node run --mode <MODE> --accept-operators-terms-and-conditions`, or alternatively paste this command with a correct path to your binary to your `ExecStart` line into a [systemd `nym-node.service`](configuration.md#systemd) config file.

**Below is a step by step guide how to initialise and run `nym-node`. Each tab represents one functionality.**

<RunTabs />

<Callout>
**We recommend operators to setup an [automation](configuration.md#systemd) flow for their nodes, using systemd!**

In such case, you can `run` a node to initalise it or try if everything works, but then stop the proces and paste your entire `run` command syntax (below) to the `ExecStart` line of your `/etc/systemd/system/nym-node.service` and start the node as a [service](configuration.md#following-steps-for-nym-nodes-running-as-systemd-service).
</Callout>

## Migrate

<Callout type="warning">
**Legacy binaries `nym-mixnode` and `nym-gateway` had been deprecated, [`nym-node`](../nym-node.mdx) is the only binary to use for `gateway` or `mixnode` functionalities!**

From `2024.14-crunch` release (`nym-node v1.2.0`) onward, `nym-node` binary does *not* have `migrate` command included. In case you are still running a legacy node and want to migrate, [download](https://github.com/nymtech/nym/releases) an older `nym-node` binary and upgrade to the latest after migrating.

Furthermore, giving that legacy nodes had been deprecated for several months, Nym cannot promise 100% serialisation for operators migrating from long outdated versions. If you are about to migrate, start with  [`nym-node v1.1.0`](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2024.3-eclipse) and keep upgrading version by version all the way to the latest one.
</Callout>

Operators who are about to migrate their nodes need to configure their [VPS](../preliminary-steps/vps-setup) and setup `nym-node` which can be downloaded as a [pre-built binary](../../binaries/pre-built-binaries) or compiled from [source](../../binaries/building-nym).

To migrate a `nym-mixnode` or a `nym-gateway` to `nym-node` use, the `migrate` command with `--config-file` flag pointing to the original `config.toml` file, with a conditional argument defining which type of node this configuration belongs to. The exact steps are below.

Make sure to use `--deny-init` flag to prevent initialisation of a new node.

<MigrateTabs />

**After you upgraded your node to the latest release of `nym-node`, make sure that you also follow [the steps to migrate your node in the Mixnet smart contract](bonding#migrate-to-nym-node-in-mixnet-smart-contract), othewise your node will never receive any rewards.**


## Functionality & Performance Check

We have a chapter called [Performance Monitoring & Testing](/operators/performance-and-testing) including much more information and tooling. If you want to just quickly check your nodes performance, connectivity and much more, visit [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/).

For more information about available endpoints and their status, you can refer to:
```sh
# sustitude <IPv4_ADDRESS> or <HOSTNAME> with the one corresponding to your node
# for http
http://<IPv4_ADDRESS>:8080/api/v1/swagger/#/
# or
http://<IPv4_ADDRESS>/api/v1/swagger/#/

# for reversed proxy/WSS
https://<HOSTNAME>/api/v1/swagger/#/
```

For example to determine which mode your node is running, you can check the `:8080/api/v1/roles` endpoint:
```sh
# sustitude <IPv4_ADDRESS> or <HOSTNAME> with the one corresponding to your node
# for http
http://<IPv4_ADDRESS>:8080/api/v1/roles
# or
http://<IPv4_ADDRESS>/api/v1/roles

# for reversed proxy/WSS
https://<HOSTNAME>/api/v1/roles
```

## Next steps

If there are any problems checkout the troubleshooting section or report an issue.

Follow up with [configuration](configuration.mdx) page for automation, reversed proxy setup and other tweaks, then head straight to [bonding](bonding.mdx) page to finalise your setup.