Start a Rubix Node

Starting a Rubix node is a three-step process:

1. Init Config — generate config.toml for the node
2. Setup Postgres — run the PostgreSQL backend in Docker
3. Run Rubix — start the node

Before you begin, make sure you have completed the Install Rubix steps (binaries + Docker).

---

0. Init Config

From the directory containing the rubixgoplatform executable, run:

./rubixgoplatform init -p <config directory>

-p is the flag used to define the config directory (node0, node1, or any name you choose).

Inside the folder defined by -p, you will find a config.toml file which defines the configuration for Rubix.

Edit config.toml

As a new user, you only need to change two fields — node_index and network_mode. Everything else can be left at its defaults: all ports are derived automatically from node_index, and the default [db] credentials already match the Docker command in the next step.

• node_index — A unique number per node. All of the node's ports are auto-assigned from this value, including the Postgres port Rubix expects, (5433 + node_index). For node_index = 0, Postgres is expected on 5433; for node_index = 1, on 5434; and so on.
• network_mode — Set this to "localnet" for local token testing. Use "testnet" or "mainnet" for the public networks.

Example minimal [core] section:

[core]
node_index = 0
network_mode = "localnet"
enable_trusted_network = false

That's all you need to start a node. The full field-by-field reference is available at the bottom of this page if you ever need it.

---

1. Setup Postgres

Run the PostgreSQL backend as a Docker container:

docker run --name my-postgres-1 \
  -e POSTGRES_PASSWORD=rubixpass \
  -e POSTGRES_USER=rubix \
  -e POSTGRES_DB=rubix \
  -p 5433:5432 \
  -v pgdata:/var/lib/postgresql \
  --restart always \
  -d postgres

A few things to note about this command:

• -p 5433:5432 — The left value is the host port where Postgres will be exposed. The formula is (5433 + node_index). For node_index = 0, use -p 5433:5432. For node_index = 1, use -p 5434:5432.
• -v pgdata:/var/lib/postgresql — The left value (pgdata) is the Docker volume where Postgres data is stored. Keep this the same across restarts to preserve your data.
• --restart always — Auto-starts the container on system reboot.
• One Docker container = one Rubix node backend. If you run multiple nodes on the same machine, run a separate Postgres container for each (with a unique --name and host port).

Make sure the credentials (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB) match the [db] section of your config.toml.

---

2. Run Rubix

Start the node by pointing it at the config directory you created in step 0:

./rubixgoplatform run -p <config directory>

The node will read config.toml from the directory and start with the configured network_mode, node_index, and database settings.

---

Configuration Reference

You do not need this to get started — node_index and network_mode are the only fields a new user changes. This is a complete reference for the rest of config.toml, kept here for when you need to tune the node.

Show full config.toml reference

The config.toml file generated by init has the following sections:

[core]

Field	Description
node_index	Unique index for the node. All ports (Rubix server, IPFS, Postgres expected port, etc.) are auto-assigned based on this value.
network_mode	Network to connect to: "localnet", "testnet", or "mainnet".
enable_trusted_network	Set to true to skip DHT checks in trusted environments.

[db]

Field	Description
host	PostgreSQL server host (typically "localhost").
username	PostgreSQL username — must match POSTGRES_USER in the Docker command.
password	PostgreSQL password — must match POSTGRES_PASSWORD in the Docker command.
db_name	PostgreSQL database name — must match POSTGRES_DB in the Docker command.

[db.config]

Field	Description
max_connections	Maximum number of DB connections in the pool.
min_connections	Minimum number of DB connections in the pool.
max_connection_lifetime_seconds	Maximum lifetime of a connection.
max_connection_idletime_seconds	Maximum idle time before a connection is closed.
statement_timeout_seconds	Timeout for DB statements.

[ipfs]

Bootstrap nodes for peer discovery on each network (mainnet_bootstrap_nodes, testnet_bootstrap_nodes, localnet_bootstrap_nodes). The defaults are the official Rubix bootstrap nodes. Modify only if you are running a custom subnet.

Port Assignment

Ports are automatically calculated from node_index:

Port	Base	Formula
Rubix Server	20000	20000 + node_index
Sender	21000	21000 + node_index
Receiver	22000	22000 + (1000 * node_index)
IPFS	5002	5002 + node_index
Swarm	4002	4002 + node_index
IPFS API	8081	8081 + node_index
PostgreSQL (expected)	5433	5433 + node_index

To run multiple nodes on the same machine, assign each one a unique node_index (and a matching Postgres container on the expected host port).

---

Your node is now running. The next step is to create a DID, which every node needs before it can hold tokens or transact.