View source for Installing Reticulum

How to get Reticulum onto the machines people actually have.

== Out of the box: you probably do not need this page ==

If you want to use the network from a laptop or phone, install an app that bundles Reticulum and configures it for you:

{| class="wikitable"
! App !! Runs on !! Get it
|-
| '''MeshChatX''' || Windows, macOS, Linux, Android || [https://meshchatx.com meshchatx.com]
|-
| '''Sideband''' || Android, Windows, macOS, Linux || [https://github.com/markqvist/Sideband/releases GitHub releases]
|-
| '''Retichat''' or '''Columba''' || iPhone || [https://apps.apple.com/us/app/retichat/id6762225314 App Store], [https://github.com/torlando-tech/Columba-iOS GitHub]
|}

[[Connecting to ScotMesh]] walks you through MeshChatX step by step, and [[Choosing a client]] compares them. Come back here when you want Reticulum on a server or a Raspberry Pi, want Nomad Network or the command-line tools, or want to see what is going on underneath.

== Full installation ==

Reticulum is a Python program. On every platform the install is <code>pip install rns</code>, with one wrinkle per platform.

=== Linux ===

On Ubuntu 24.04, Debian 12 and other recent distributions, a system-wide <code>pip install</code> is refused with <code>error: externally-managed-environment</code>. That is deliberate on the distribution's part (PEP 668), not a fault. Use a virtual environment:

<syntaxhighlight lang="text">sudo apt install python3-venv
python3 -m venv ~/reticulum
~/reticulum/bin/pip install rns</syntaxhighlight>

The commands are then <code>~/reticulum/bin/rnsd</code>, <code>~/reticulum/bin/rnstatus</code> and so on. To have them on your path, add <code>export PATH=~/reticulum/bin:$PATH</code> to <code>~/.bashrc</code>.

<code>pipx install rns</code> also works, if you have pipx, and puts the commands on your path for you.

On a Raspberry Pi the same applies. A Pi Zero 2 or later is plenty.

=== macOS ===

Install Python 3 from [https://www.python.org python.org] or with Homebrew (<code>brew install python</code>), then:

<syntaxhighlight lang="text">pip3 install rns</syntaxhighlight>

If pip refuses for the same PEP 668 reason, use a virtual environment exactly as for Linux.

=== Windows ===

Install Python 3 from [https://www.python.org python.org], ticking '''Add Python to PATH''' in the installer. Then in a terminal:

<syntaxhighlight lang="text">pip install rns</syntaxhighlight>

The config file lands in <code>C:\Users\&lt;you&gt;\.reticulum\config</code>.

=== Android ===

Use one of the apps above; both Android apps bundle Reticulum. Running it by hand under Termux is possible but fiddly and gains you nothing for ordinary use.

=== First run ===

Run <code>rnsd</code> once. It creates <code>~/.reticulum/config</code> and stops when you press Ctrl+C. Then add an interface to ScotMesh as described in [[Connecting to ScotMesh#Full installation: Reticulum yourself|Connecting to ScotMesh]], start it again, and check with <code>rnstatus</code>.

=== Keeping it running ===

Reticulum only works while <code>rnsd</code> is running. On Linux, run it as a systemd service so it starts at boot; the unit file is in [[Connecting to ScotMesh#Keeping it running|Connecting to ScotMesh]]. On macOS and Windows, leave the terminal open, or use MeshChatX, which keeps its own Reticulum running while the app is open.

=== Checking it works ===

<syntaxhighlight lang="text">rnstatus</syntaxhighlight>

Each interface should show '''Status: Up''' and traffic that rises over the first minute or two. [[Troubleshooting]] explains the output line by line and what to do when it is not Up.

=== Updating ===

<syntaxhighlight lang="text">pip install --upgrade rns</syntaxhighlight>

(with the same path prefix if you used a virtual environment), then restart <code>rnsd</code>. Reticulum releases are backwards compatible on the wire, so you do not have to update in step with anyone else.

[[Category:Getting Started]]