Your own config.toml

What survives, what gets rewritten

quai-node regenerates the whole of config/config.toml from quai-node.toml whenever it saves its settings, and merges in extra.toml. It doesn't keep what was in the old file: edits made to config.toml itself are dropped.

quai-node.toml and extra.toml are never lost: setup reads them back. private.key and the chain data aren't touched either. Only uninstall --purge removes those.

Keys quai-node owns

These are written on every save. Change them in quai-node.toml (or with setup's flags). extra.toml refuses them, because quai-node acts on its own copy: the snapshot restore writes to data_dir, for instance, and the dashboard reads the RPC where quai-node put it.

To change one of these, edit quai-node.toml and re-apply it. That rewrites the configs and restarts the service:

# e.g. p2p_port = 4010
$EDITOR ~/.local/share/quai-node/quai-node.toml
quai-node setup --apply

Adding your own keys

1 · see every key go-quai has

go-quai prints its full default config with go-quai config. It needs its VERSION file in the folder it runs from, and it won't overwrite an existing config.toml. So run it in a scratch folder:

mkdir -p /tmp/go-quai-defaults && cd /tmp/go-quai-defaults
cp ~/.local/share/quai-node/VERSION .
~/.local/share/quai-node/bin/go-quai config --global.config-dir .
less config.toml

That gives you about 110 keys in the tables [global], [metrics], [node], [peers], [rpc], [txpool] and [workshare], with their defaults. It writes only to that folder: config.toml and a nodelogs/ with one log. Every key is also a flag. ~/.local/share/quai-node/bin/go-quai start --help describes each one, and it runs from any folder.

2 · put them in extra.toml

Open config/extra.toml. Setup leaves a commented one there. Use go-quai's tables and key names, and copy each value's type from the defaults dump: some numbers are strings in go-quai, like max-peers = '50'.

# config/extra.toml
[metrics]
enabled = true

[node]
max-peers = '100'

quai-node merges these into the tables it writes, so [node] here and the [node] in config.toml become one table. It checks the file first, before changing anything, and refuses three things, naming the file and the key:

• a key quai-node writes itself (section 3): it says which quai-node.toml setting to change instead
• a table go-quai doesn't have, such as [metric]
• a key outside any table, or a table inside a table

A misspelled key inside a real table can't be caught: go-quai ignores keys it doesn't know without a word. Check spellings against the dump.

3 · apply and check

quai-node setup --apply
quai-node status
quai-node logs

setup --apply rewrites config.toml with your keys merged in, lists which keys it took from extra.toml, and restarts the service. If the node doesn't come back, the reason is in the service's log. On systemd that's journalctl -u quai-node; setup prints where it is for your system.

Recipes

Key names, defaults and descriptions are from go-quai v0.56.1's flags. Each goes in extra.toml, followed by quai-node setup --apply.

prometheus metrics

Off by default. Only enabled is needed: the address and port shown are go-quai's defaults, loopback on 6060, where a local Prometheus or an SSH tunnel can reach them.

[metrics]
enabled = true
metrics-addr = '127.0.0.1'
metrics-port = 6060

more or fewer peers

Defaults are 5 and 50. Fewer peers means less bandwidth; more means a better-connected node.

[node]
min-peers = '8'
max-peers = '100'

announce a public address

If the node sits behind a NAT that UPnP can't open, you can forward the port yourself and tell peers where to reach you. The value is a multiaddr, and the port has to match p2p_port.

[node]
external-addr = '/ip4/203.0.113.7/tcp/4002'

a bigger cache

node.cache is the memory, in megabytes, go-quai gives its internal caches. It defaults to 1024. On a machine with RAM to spare, raising it means fewer disk reads:

[node]
cache = 4096

mining: which coin, which interface

miner-preference runs from 0 (Quai only) to 1 (Qi only), with 0.5 neutral, the default. The three stratum endpoints listen on every interface by default. To keep them to one LAN address, set them here. stratum-api-addr is quai-node's, because the dashboard reads it.

[node]
miner-preference = 0.5
stratum-kawpow-addr = '192.168.1.20:3333'
stratum-scrypt-addr = '192.168.1.20:3334'
stratum-sha-addr = '192.168.1.20:3335'

coinbase-lockup chooses how long coinbase rewards stay locked. It's a protocol setting with consequences for your payouts, so read go-quai's docs on lockups before you change it.

an index of the whole chain

By default go-quai keeps its transaction index for about the last year of blocks. 0 indexes the whole chain, which costs disk. index-address-utxos adds an index of Qi outputs by address.

[node]
txlookuplimit = 0
index-address-utxos = true

logs

The level runs from trace through panic. Logs roll at log-size megabytes (default 500) and land in nodelogs/, one file per chain.

[global]
log-level = 'debug'
log-size = 200

a health endpoint

An HTTP check for a load balancer or an uptime monitor. It answers 503 when the node trails the reference nodes in health-urls by more than health-max-behind blocks (default 5). The default reference is https://rpc.quai.network/cyprus1, so this check adds requests from your node to it.

[rpc]
health = true
health-port = 8081

about node.telemetry

go-quai sets node.telemetry = true by default. In v0.56.1 it keeps an in-memory record of recent workshares, which a debug RPC call can dump. It sends nothing off the machine, so leaving it on doesn't contradict quai-node's no-telemetry line.

Don't break the wiring

• RPC ports and address. The dashboard and quai-node status read the node at 127.0.0.1: ports 9001 (prime), 9002 (region) and 9200 (cyprus1). Move them and the node keeps running, but the dashboard and status go blind.
• Opening the RPC. go-quai's RPC has no login. rpc.http-addr is quai-node's, and it opens it to 0.0.0.0 only when you join Keepers, which needs it. rpc.ws-addr isn't, and binding it to 0.0.0.0 lets anyone who can reach the port use it. Reach the node over SSH or a VPN instead.
• config/private.key is the node's identity on the network, and a claimed Keepers tag is locked to it. Keep it when you move a node, and the tag moves with it.
• unlock, password, private-key and other keys that handle keys: quai-node never needs them. Mining pays to addresses, so no private key has to live on the node.

Keeping your keys across updates

Keys in extra.toml need nothing extra: an update rewrites config.toml and merges them back in, and setup lists the ones it took.

still on v0.1.0?

quai-node v0.1.0 has no extra.toml. You edit config.toml inside its existing tables, and an update writes it fresh. Don't add a second [node] header at the bottom: TOML forbids defining a table twice, and go-quai stops at start with toml: table node already exists. Keep your version beside it and compare after each update:

cd ~/.local/share/quai-node/config
# once your edits work:
cp config.toml config.toml.mine

# update:
curl -fsSL https://quainode.org/install.sh | sh

# see what the update reset, then put your keys back:
diff config.toml.mine config.toml
$EDITOR config.toml
quai-node service restart

Read the diff before copying config.toml.mine back over the new file. An update can change keys quai-node owns (section 3), and the fresh file has those right. Once an update brings extra.toml, move your keys there and delete config.toml.mine.

or run go-quai yourself

To own the config outright, take go-quai out of quai-node's service. Uninstall the service with quai-node service uninstall, then start go-quai from your own unit with your own config folder, from the quai-node home. Use the same command the service uses, with a different --global.config-dir. quai-node then serves as the installer and updater of the binaries in bin/. When you update, tell setup not to install the service (--no-service). The dashboard ran inside quai-node's service, so give it a unit too: bin/quai-dash --config <home>/dash/config.toml web. It and quai-node status keep working as long as the RPC stays where section 6 says.