Configuration
Overview
Reticulum-Go reads the same INI-style configuration shape as Python Reticulum. The canonical parser lives in pkg/reticulumconfig. The daemon imports it through internal/config.
Default config path:
~/.reticulum-go/configOverride with --config on the daemon command line.
Config directory layout
~/.reticulum-go/
config
storage/
identities/
cache/
announces/
resources/
ratchets/
blackhole
destination_table
known_destinations/
transport_identityPython uses ~/.reticulum or /etc/reticulum by default. Reticulum-Go uses a separate directory so both stacks can run on one host.
File format
| Aspect | Behavior |
|---|---|
| Sections | [reticulum], [logging], [[Interface Name]] |
| Interface blocks | Double-bracket headers at nesting depth 2 |
| Comments | # or ; (including end-of-line after a space) |
| Booleans | yes, no, true, false, on, off, 1, 0 (case insensitive) |
| Unknown keys | Ignored (allows boot with extra or damaged lines) |
| UTF-8 BOM | Stripped on read |
| Missing file | Default config is created |
Section [reticulum]
| Key | Default | Description |
|---|---|---|
enable_transport |
yes | Enable transport routing and path table |
share_instance |
yes | Use shared instance multiplexing |
shared_instance_port |
37428 | TCP port for shared instance |
instance_control_port |
37429 | Control port when this process owns the instance |
shared_instance_type |
tcp | tcp or unix |
instance_name |
(empty) | Unix socket name when type is unix |
rpc_key |
(empty) | Hex key for shared-instance RPC and control API auth |
enable_sandbox |
yes | Apply OS sandbox after startup (Go-only) |
enable_seccomp |
yes | Linux seccomp-bpf denylist after Landlock (ignored when sandbox is off, soft-fails if unsupported) |
enable_control_api |
no | Start localhost control API |
control_api_host |
127.0.0.1 | Control API bind address |
control_api_port |
37430 | Control API port |
backbone_io |
auto | Backbone poller: auto, epoll, kqueue, io_uring, go |
in_memory_path_table |
no | Keep path table in RAM only |
in_memory_known_destinations |
no | Keep known destinations in RAM only |
in_memory_storage |
no | Fully ephemeral mode: no disk for paths, known dests, transport identity, blackhole, or split resources. Implies both table flags |
identity_backend |
file | Identity at-rest store: file, secretservice (Freedesktop Secret Service), or keyring (Linux kernel keyring) |
soft_memory_limit |
(none) | Soft heap budget (K/M/G or bytes) via Go debug.SetMemoryLimit |
max_in_memory_paths |
100000 | Path table soft cap when in_memory_storage is yes. Negative disables |
max_in_memory_known_destinations |
100000 | Known-dest soft cap when in_memory_storage is yes. Negative disables |
max_in_memory_resource_bytes |
256M | Split-resource staging budget when in_memory_storage is yes. Negative disables |
discover_interfaces |
no | Start rnstransport interface discovery listener |
watch_interfaces |
no | Poll NIC up/down and rescan Auto interfaces (Go-only) |
static_transport_identity |
no | Keep persisted transport identity on the wire when enable_transport is no (RNS 1.3.6+) |
local_hops_delta |
no | Mangling applied on local-origin hop-0 packets (delta 2-7) |
respond_to_probes / allow_probes |
no | Register rnstransport.probe with prove-all |
network_identity |
(empty) | Path to network identity for discovery encrypt/decrypt |
panic_on_interface_error |
no | Panic on fatal interface errors |
Keys present in Python but ignored in Go
| Key | Notes |
|---|---|
publish_blackhole |
Blackhole auto-publish not started |
blackhole_sources |
Ignored |
blackhole_update_interval |
Ignored |
local_hops_delta applies a random hop field (2-7) on locally originated hop-0 packets when not connected to a shared instance.
Section [logging]
| Key | Supported |
|---|---|
loglevel |
Yes (0 through 7) |
destination |
Yes (stderr, file, both, syslog, journald, and combinations such as syslog+stderr) |
logfile |
Yes (default {config_dir}/logfile/reticulum.log) |
format |
Yes (text or json) |
Interface blocks [[Name]]
Each block defines one interface. Common keys:
| Key | Applies to | Description |
|---|---|---|
type |
All | Interface type string (see Interfaces) |
enabled / interface_enabled |
All | Enable or disable |
mode / interface_mode |
All | full, gateway, access_point, roaming, boundary, ptp, internal (RNS 1.3.6+) |
recursive_prs |
All | Discover unknown paths on this interface (RNS 1.3.6+) |
announces_from_internal |
All | Rebroadcast announces learned via internal-mode next hops (default yes) |
address / listen_ip |
UDP, TCP/QUIC/WebTransport/HTTPS server, DNSRendezvous | Bind address |
port / listen_port |
UDP, TCP/QUIC/WebTransport/HTTPS/VSOCK server, DNSRendezvous | Bind or VSOCK port |
target_host / target_port |
TCP, QUIC, WebTransport, HTTPS client | Remote peer |
target_address |
UDP | Remote peer (preferred over target_host) |
interface |
Auto | OS network interface name |
prefer_ipv6 |
TCP, Auto | Prefer IPv6 when available |
max_reconnect_tries |
TCP, UDP, backbone, QUIC, WebTransport, HTTPS, VSOCK | -1 or omitted means unlimited |
bitrate |
All | Declared bitrate hint |
mtu |
All | Interface MTU (default packet MTU is 500 bytes) |
discovery_port |
Auto | Multicast discovery port |
data_port |
Auto | Data port |
discovery_scope |
Auto | Multicast scope |
group_id |
Auto | Group identifier |
multicast_address_type |
Auto | Multicast address type |
announce_cap |
All | Cap on outbound announces |
announce_rate_* |
All | Announce rate control |
ingress_control / ic_* |
All | Ingress rate limits |
network_name |
IFAC | IFAC network name |
passphrase |
IFAC | IFAC passphrase |
ifac_* |
IFAC | Additional IFAC options |
sam_address |
I2P | SAM server host:port |
peers |
I2P | Outbound tunnel peers |
connectable |
I2P | SAM server tunnel mode |
i2p_tunneled |
TCP client, backbone client | Tunnel over I2P |
command |
Pipe | External program for stdin/stdout HDLC bridge |
respawn_delay / respawn_interval |
Pipe | Seconds before respawning subprocess (default 5) |
shared_instance_type |
Local | tcp or unix for explicit local interface blocks |
instance_name |
Local | Unix socket name when type is unix |
cert_file / key_file |
QUIC, WebTransport, HTTPS | Optional TLS PEM paths |
peer_key |
QUIC, WebTransport, HTTPS | Leaf SPKI SHA-256 pin (hex) |
sni |
QUIC, WebTransport, HTTPS client | TLS ServerName |
path |
WebTransport, HTTPS | URL path (default /rns) |
transport_mode |
WebTransport | datagram, stream, or dual |
domain |
DNSRendezvous | DNS name for TXT lookup |
resolve_interval |
DNSRendezvous | Seconds between TXT re-queries (default 60) |
context_id / cid |
VSOCK client | Peer AF_VSOCK context ID |
long_poll_sec |
HTTPS | Long-poll timeout seconds (default 25) |
outgoing / selected_outgoing |
All | Transmit permit (default yes). When no, interface is receive-only |
Unknown type values load Go-native plugins from {config_dir}/interfaces/ (JSON manifest or executable pipe driver), or from interfaces.RegisterExternalFactory.
Interface types
type value |
Implementation |
|---|---|
UDPInterface |
pkg/interfaces/udp.go |
TCPClientInterface |
pkg/interfaces/tcp.go |
TCPServerInterface |
pkg/interfaces/tcp.go |
AutoInterface |
pkg/interfaces/auto.go |
I2PInterface |
pkg/interfaces/i2p.go |
BackboneInterface |
pkg/interfaces/backbone.go |
BackboneClientInterface |
pkg/interfaces/backbone_client.go |
PipeInterface |
pkg/interfaces/pipe.go |
LocalInterface |
pkg/interfaces/local.go (client to shared instance) |
LocalServerInterface |
pkg/interfaces/local.go (explicit server block) |
WebSocketInterface |
Go-only, native or WASM |
QUICClientInterface |
Go-only, native (quic-go) |
QUICServerInterface |
Go-only, native (quic-go) |
WebTransportClientInterface |
Go-only, HTTP/3 WebTransport |
WebTransportServerInterface |
Go-only, HTTP/3 WebTransport |
DNSRendezvousInterface |
Go-only, DNS TXT to UDP peer |
VSOCKClientInterface |
Go-only Linux, AF_VSOCK HDLC |
VSOCKServerInterface |
Go-only Linux, AF_VSOCK HDLC |
HTTPSClientInterface |
Go-only, TLS long-poll |
HTTPSServerInterface |
Go-only, TLS long-poll |
Example: TCP client with IFAC
[[Gateway]]
type = TCPClientInterface
enabled = yes
target_host = mesh.example.com
target_port = 7825
network_name = MyMesh
passphrase = long-random-secret
ifac_size = 16
max_reconnect_tries = 0max_reconnect_tries = 0 means no reconnect attempts after disconnect. Omit the key or set -1 for unlimited retries.
Example: QUIC client and server
[[QUIC Hub]]
type = QUICServerInterface
enabled = yes
listen_ip = 0.0.0.0
listen_port = 4242
[[QUIC Uplink]]
type = QUICClientInterface
enabled = yes
target_host = hub.example.com
target_port = 4242
peer_key = aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899
max_reconnect_tries = -1QUIC is Go-only. TLS uses ephemeral self-signed certificates by default. Set peer_key to the remote leaf SPKI SHA-256 (hex) to pin the peer. Optional cert_file / key_file and sni are supported. Not available on WASM.
Example: AutoInterface on Wi-Fi
[reticulum]
watch_interfaces = yes
[[WiFi Mesh]]
type = AutoInterface
enabled = yes
interface = wlan0
discovery_port = 35615
data_port = 35616watch_interfaces rescans NICs when link state changes and helps AutoInterface follow Wi-Fi roam events.
Example: PipeInterface subprocess bridge
[[Radio Bridge]]
type = PipeInterface
enabled = yes
command = /opt/mesh/radio-bridge --stdio
respawn_delay = 5Reticulum writes HDLC-framed packets to the subprocess stdin and reads frames from stdout. When the subprocess exits, the interface respawns after respawn_delay seconds.
Example: shared-instance RPC for Go CLI tools
Python rnsd on Linux defaults to an abstract Unix RPC socket. Go rgostatus dials TCP 127.0.0.1:instance_control_port when shared_instance_type = tcp. To let Go tools talk to Python (or the reverse), set the same TCP settings and preferably the same rpc_key in the daemon config:
[reticulum]
share_instance = yes
instance_name = default
shared_instance_type = tcp
shared_instance_port = 37428
instance_control_port = 37429
rpc_key = <64 hex characters>Restart the daemon after changing these keys. Query with:
make build
./bin/reticulum-go status -config ~/.reticulum -jsonUse -config ~/.reticulum for Python rnsd and -config ~/.reticulum-go for a Go shared instance. Full utility docs are in CLI utilities.
Example: explicit LocalInterface client
When share_instance = no, attach to another process that owns the shared instance:
[reticulum]
share_instance = no
[[Local]]
type = LocalInterface
enabled = yes
port = 37428
shared_instance_type = tcpHot reload
On Unix the daemon reloads interface blocks on SIGHUP via node.ReloadInterfaces. Reload compares normalized config for each interface including MTU, bitrate, prefer_ipv6, announce-rate, ingress/egress control, mode, and outgoing. See Interfaces.
Programmatic access
import "quad4/reticulum-go/pkg/reticulumconfig"
cfg, err := reticulumconfig.LoadConfig("/path/to/config")Defaults without a file:
cfg := reticulumconfig.DefaultConfig()Save:
err := reticulumconfig.SaveConfig(cfg)Storage and identity files
Identity files use a 64-byte software layout (X25519 private plus Ed25519 seed). Reticulum-Go stores identity blobs under storage/identities/ keyed by hash. Python may use per-name files. Both layouts are supported for loading.
Optional hardware-bound descriptors (RHB1, 72 bytes) are documented in Identity and destinations.
Related documents
- Interfaces for per-type behavior and reconnect policy
- Architecture for shared instance and persistence
- CLI utilities for
rgostatus/rgoid/rgoprobeand RPC setup - COMPATIBILITY.md for full Python key comparison tables