8.4 KiB
Getting started
Requirements
- Go 1.26.5 or later
- Make or Task (optional, for convenience targets)
- A writable home directory for ~/.reticulum-go
The repository vendors dependencies. A normal build does not contact module proxies when GOFLAGS=-mod=vendor is set (default in the Makefile and Taskfile).
Build
From the repository root (Make, Task, or plain Go):
make build
# or
task build
This produces bin/reticulum-go as a static stripped binary (CGO_ENABLED=0) with the daemon and all tools as subcommands.
Manual:
mkdir -p bin
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/reticulum-go ./cmd/reticulum-go
Install to PATH
The root install.sh script can fetch a release binary or build from source, pick GOAMD64=v3 on capable linux/amd64 CPUs, and install systemd, OpenRC, runit, or dinit service files:
curl -fsSL https://raw.githubusercontent.com/Quad4-Software/Reticulum-Go/master/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/Quad4-Software/Reticulum-Go/master/install.sh | sh -s -- --dry-run
./install.sh --source --init systemd
From a checkout with Make or Task:
make install
# or
task install
Default prefix is /usr/local. That installs reticulum-go, legacy tool symlinks (rgostatus, rgoid, …), and man pages (reticulum-go(1), reticulum-go(8), and tool pages). Override with make install PREFIX=/opt/reticulum. Staging: make install DESTDIR=/tmp/stage PREFIX=/usr.
Init units:
make install-service
make install-service INIT=systemd
Or install into your Go binary directory:
CGO_ENABLED=0 go install -ldflags="-s -w" ./cmd/reticulum-go
Linux packages:
make package-deb
make package-rpm
make package-arch
Arch Linux and CachyOS: add the Quad4 pacman repo from quad4-arch (reticulum-go or reticulum-go-git). That is a Quad4-hosted repo, not AUR.
Full Make/Task target map: Development and testing.
First run
make run
# or
task run
# or
go run ./cmd/reticulum-go
On first start the daemon creates ~/.reticulum-go/ with a default config if none exists. Logs go to stderr by default. Set verbosity with [logging] loglevel (0 silent through 7 packets, default 4 info). Set [logging] destination = file|both and optional logfile to write to disk (default {config_dir}/logfile/reticulum.log). Daemon text logs, pageserver banner, and CLI tools color on TTY. Respect NO_COLOR and FORCE_COLOR / CLICOLOR_FORCE.
Daemon flags:
reticulum-go --config ~/.reticulum-go/config -debug 5
reticulum-go --config /path/to/config-dir
Custom config path
Pass --config / -config with a config file or directory (directory uses config inside it).
Minimal configuration
A useful starting point enables transport and one UDP interface to a known peer:
[reticulum]
enable_transport = yes
share_instance = yes
[logging]
loglevel = 4
[[UDP Peer]]
type = UDPInterface
enabled = yes
interface_enabled = yes
target_address = 192.0.2.10
target_port = 4242
port = 4242
UDP requires an explicit target_address or target_host. Open binds do not learn peers from the first inbound packet (same policy as Python forward_ip).
For local mesh discovery over IPv6 link-local multicast, use AutoInterface. See Interfaces.
Verify the build
make test-short
# or
task test-short
# or
go test -short -v ./...
Full test suite:
make test
# or
task test
# or
go test -v ./...
Cross-reference tests against Python vectors (requires Python 3 and vector generation):
./tests/crossref/run_crossref.sh all
Cross-platform builds
make build-linux
make build-windows
make build-darwin
make build-all
Linux amd64 always ships GOAMD64 v1 (unsuffixed and -v1) together with -v3. linux/386 is also named linux-i686. make build-all covers every CGO-free target listed in scripts/build-release-targets.sh.
Legacy Windows 7, 8, and 8.1 builds use go-legacy-win7:
make build-windows-legacy
# or
task build-windows-legacy
Windows XP and Server 2003 builds use go-legacy-winxp:
make build-windows-xp
# or
task build-windows-xp
WebAssembly
task build-wasm
make test-wasm
# or
task test-wasm
Manual:
mkdir -p bin
GOOS=js GOARCH=wasm go build -ldflags="-s -w" -o bin/reticulum-go.wasm ./cmd/reticulum-wasm
See Embedding and WebAssembly.
librns and language bindings
Build the shared library and optional binding tests:
make build-librns
# or: task build-librns
make -C bindings/c/examples/smoke && ./bindings/c/examples/smoke/librns-smoke
make test-odin
# or: task test-odin / task test-zig / task test-cpp
Odin bindings need the Odin compiler on PATH. Zig needs 0.16.0 or later. C++ needs CMake and a C++17 compiler. See librns.
Dart bindings
make build-librns
task test-dart
# or: make test-dart
Needs the Dart SDK on PATH. FFI uses librns on Linux, Android, and Windows. See librns and Control API.
Enable the control API
Add to [reticulum]:
enable_control_api = yes
rpc_key = <64 hex characters>
control_api_host = 127.0.0.1
control_api_port = 37430
Generate a random 32-byte key and encode as hex. Clients send Authorization: Bearer <rpc_key>. See Control API.
CLI utilities (status, identity, probe, path, copy, pageserver)
Tools are subcommands of the single reticulum-go binary (make build). Legacy names (rgostatus, …) install as symlinks via make install.
To query a running Python rnsd from reticulum-go status / path, point -config at ~/.reticulum. On Linux both stacks default to abstract Unix sockets when shared_instance_type is unset, so no TCP rewrite is required:
./bin/reticulum-go status -config ~/.reticulum -json
./bin/reticulum-go path -config ~/.reticulum -t -json
Prefer an explicit shared rpc_key when mixing stacks. Use shared_instance_type = tcp only when you want the same recipe on every OS.
Full flag reference, .rsg / .rsm / .rfe usage, file transfer, and troubleshooting are in CLI utilities.
Disable the sandbox
Sandboxing is on by default. To turn it off (not recommended for production):
enable_sandbox = no
See Security for platform behavior.
Troubleshooting
Daemon exits on config error. Check the config path and syntax. Unknown keys are ignored so a damaged file can still boot. Fix typos in type and interface names.
No paths to remote destinations. Confirm interfaces are enabled, peers are reachable, and transport is enabled. Use debug level 5 or higher temporarily. Request paths explicitly from application code or the control API.
IFAC mismatches. Peers must use the same network_name and passphrase. Wrong IFAC frames are dropped silently on ingress.
Shared instance conflicts. Only one process should own interfaces when share_instance = yes. Others should connect as clients. Check shared_instance_port (default 37428).
status connection refused. Point -config at the daemon config dir (~/.reticulum for rnsd). Align shared_instance_type and instance_name / ports, or leave the type unset on Linux for Unix. See CLI utilities.
Permission errors on Linux sandbox. Landlock requires kernel 5.13+. The config directory and storage paths must live under whitelisted locations. See Security.
Next steps
| Goal | Document |
|---|---|
| Configure interfaces and rates | Configuration, Interfaces |
| Status / identity / probe / path / copy CLIs | CLI utilities |
| Write a Go app | API reference, Examples, Embedding and WebAssembly |
| Embed from C or Odin | librns, Examples |
| Flutter / Dart | librns Dart FFI, Control API, Examples |
| Talk to a running daemon | Control API |
| Run in Firecracker | Firecracker microvm (make microvm-up) |
| Use Python interop | Compatibility |
| Run examples | Examples |