<linkrel="index"title="Index"href="genindex.html"><linkrel="search"title="Search"href="search.html"><linkrel="next"title="Using Reticulum on Your System"href="using.html"><linkrel="prev"title="What is Reticulum?"href="whatis.html">
<p>If you do not already have pip installed, you can install it using the package manager
of your system with a command like <codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">apt</span><spanclass="pre">install</span><spanclass="pre">python3-pip</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">pamac</span><spanclass="pre">install</span><spanclass="pre">python-pip</span></code> or similar.</p>
<p>You can also dowload the Reticulum release wheels from GitHub, or other release channels,
and install them offline using <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>:</p>
<p>On platforms that limit user package installation via <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>, you may need to manually
allow this using the <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> command line flag when installing. This
will not actually break any packages, unless you have installed Reticulum directly via
<h3>Resolving Dependency & Installation Issues<aclass="headerlink"href="#resolving-dependency-installation-issues"title="Link to this heading">¶</a></h3>
<p>On some platforms, there may not be binary packages available for all dependencies, and
<codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> installation may fail with an error message. In these cases, the issue can usually
be resolved by installing the development essentials packages for your platform:</p>
<p>With the base development packages installed, <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> should be able to compile any missing
dependencies from source, and complete installation even on platforms that don’t have pre-
<p>The <aclass="reference external"href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive
remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
remote system, and is similar to how <codeclass="docutils literal notranslate"><spanclass="pre">ssh</span></code> works. The <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
<p>If this is the very first time you use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install a program
on your system, you might need to reboot your system for your program to become
available. If you get a “command not found” error or similar when running the
program, reboot your system and try again. In some cases, you may even need to
manually add the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> install path to your <codeclass="docutils literal notranslate"><spanclass="pre">PATH</span></code> environment variable.</p>
<p>Reticulum comes with a range of included utilities that make it easier to
manage your network, check connectivity and make Reticulum available to other
programs on your system.</p>
<p>You can use <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> to run Reticulum as a background or foreground service,
and the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">rnpath</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">rnprobe</span></code> utilities to view and query
network status and connectivity.</p>
<p>To learn more about these utility programs, have a look at the
<aclass="reference internal"href="using.html#using-main"><spanclass="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p>
<p>To create a network, you will need to specify one or more <em>interfaces</em> for
Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum/config</span></code>. You can get an example
configuration file with all options via <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span><spanclass="pre">--exampleconfig</span></code>.</p>
<p>When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses
your existing Ethernet and WiFi networks (if any), and only allows you to
communicate with other Reticulum peers within your local broadcast domains.</p>
<p>To communicate further, you will have to add one or more interfaces. The default
configuration includes a number of examples, ranging from using TCP over the
internet, to LoRa and Packet Radio interfaces.</p>
<p>With Reticulum, you only need to configure what interfaces you want to communicate
over. There is no need to configure address spaces, subnets, routing tables,
or other things you might be used to from other network types.</p>
<p>Once Reticulum knows which interfaces it should use, it will automatically
discover topography and configure transport of data to any destinations it
knows about.</p>
<p>In situations where you already have an established WiFi or Ethernet network, and
many devices that want to utilise the same external Reticulum network paths (for example over
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
other device on your local WiFi will then be able to connect to this wider Reticulum
network just using the default (<aclass="reference internal"href="interfaces.html#interfaces-auto"><spanclass="std std-ref">AutoInterface</span></a>) configuration.</p>
<p>Possibly, the examples in the config file are enough to get you started. If
you want more information, you can read the <aclass="reference internal"href="networks.html#networks-main"><spanclass="std std-ref">Building Networks</span></a>
and <aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="std std-ref">Interfaces</span></a> chapters of this manual.</p>
<h2>Connecting Reticulum Instances Over the Internet<aclass="headerlink"href="#connecting-reticulum-instances-over-the-internet"title="Link to this heading">¶</a></h2>
<p>Reticulum currently offers three interfaces suitable for connecting instances over the Internet: <aclass="reference internal"href="interfaces.html#interfaces-backbone"><spanclass="std std-ref">Backbone</span></a>, <aclass="reference internal"href="interfaces.html#interfaces-tcps"><spanclass="std std-ref">TCP</span></a>
and <aclass="reference internal"href="interfaces.html#interfaces-i2p"><spanclass="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum
users should carefully choose the interface which best suites their needs.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using <codeclass="docutils literal notranslate"><spanclass="pre">I2PInterface</span></code>,
however it also leaks more data about the server host.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">BackboneInterface</span></code> is a very fast and efficient interface type available on POSIX operating
systems, designed to handle many hundreds of connections simultaneously with low memory, processing
and I/O overhead. It is fully compatible with the TCP-based interface types.</p>
<p>TCP connections reveal the IP address of both your instance and the server to anyone who can
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
which most Internet connections don’t offer anymore.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">I2PInterface</span></code> routes messages through the <aclass="reference external"href="https://geti2p.net/en/">Invisible Internet Protocol
(I2P)</a>. To use this interface, users must also run an I2P daemon in
parallel to <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <aclass="reference external"href="https://i2pd.website/">i2pd</a>.</p>
<p>By default, I2P will encrypt and mix all traffic sent over the Internet, and
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
will also relay other I2P user’s encrypted packets, which will use extra
bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult.</p>
<p>I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.</p>
<p>In general it is recommended to use an I2P node if you want to host a publicly accessible
instance, while preserving anonymity. If you care more about performance, and a slightly
<spanid="id4"></span><h2>Bootstrapping Connectivity<aclass="headerlink"href="#bootstrapping-connectivity"title="Link to this heading">¶</a></h2>
<p>Reticulum is not a service you subscribe to, nor is it a single global network you “join”. It is a <em>networking stack</em>; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.</p>
<p>One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.</p>
<p>Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.</p>
<p>There is no “right” or “wrong” way to build a Reticulum network, and you don’t need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.</p>
<sectionid="finding-your-way">
<h3>Finding Your Way<aclass="headerlink"href="#finding-your-way"title="Link to this heading">¶</a></h3>
<p>When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with. This is the process of <strong>bootstrapping</strong>.</p>
<p>A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization.</p>
<p>Reticulum encourages the approach of <em>organic growth</em>. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to <em>discover</em> better, more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.</p>
<p>It <em>is</em> possible to simply add a few public entrypoints to the <codeclass="docutils literal notranslate"><spanclass="pre">[interfaces]</span></code> section of your Reticulum configuration and be connected, but a better option is to enable <aclass="reference internal"href="using.html#using-interface-discovery"><spanclass="std std-ref">interface discovery</span></a> and either manually select relevant, local interfaces, or enable discovered interface auto-connection.</p>
<p>A relevant option in this context is the <aclass="reference internal"href="interfaces.html#interfaces-options"><spanclass="std std-ref">bootstrap only</span></a> interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as <codeclass="docutils literal notranslate"><spanclass="pre">bootstrap_only</span></code>, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.</p>
<p>A good place to find interface definitions for bootstrapping connectivity is <aclass="reference external"href="https://rmap.world/">rmap.world</a>.</p>
</section>
<sectionid="building-personal-infrastructure">
<h3>Building Personal Infrastructure<aclass="headerlink"href="#building-personal-infrastructure"title="Link to this heading">¶</a></h3>
<p>You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.</p>
<p>We strongly encourage everyone, even home users, to think in terms of building <strong>personal infrastructure</strong>. Don’t connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal <strong>Transport Node</strong>:</p>
<ulclass="simple">
<li><p>Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).</p></li>
<li><p>You configure this node with a <codeclass="docutils literal notranslate"><spanclass="pre">bootstrap_only</span></code> interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.</p></li>
<li><p>While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.</p></li>
<li><p>Your personal devices now connect to your <em>local</em> node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.</p></li>
<p><strong>Don’t wait for others to build the networks you want to see</strong>. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.</p>
<h3>Mixing Strategies<aclass="headerlink"href="#mixing-strategies"title="Link to this heading">¶</a></h3>
<p>There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.</p>
<ulclass="simple">
<li><p><strong>Static Interfaces:</strong> You maintain a permanent interface to a trusted friend or organization using a static configuration.</p></li>
<li><p><strong>Bootstrap Links:</strong> You connect a <codeclass="docutils literal notranslate"><spanclass="pre">bootstrap_only</span></code> interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.</p></li>
<li><p><strong>Local Wide-Area Connectivity:</strong> You run a <codeclass="docutils literal notranslate"><spanclass="pre">RNodeInterface</span></code> on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any “service providers” being able to control or monitor how you interact with people.</p></li>
</ul>
<p>By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.</p>
</section>
<sectionid="network-health-responsibility">
<h3>Network Health & Responsibility<aclass="headerlink"href="#network-health-responsibility"title="Link to this heading">¶</a></h3>
<p>As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the <aclass="reference internal"href="using.html#using-blackhole-management"><spanclass="std std-ref">Blackhole Management</span></a> system.</p>
<p>Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that <em>your</em> transport capacity is used for what <em>you</em> consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.</p>
<h3>Contributing to the Global Ret<aclass="headerlink"href="#contributing-to-the-global-ret"title="Link to this heading">¶</a></h3>
<p>If you have the means to host a stable node with a public IP address, consider becoming a <aclass="reference internal"href="#hosting-entrypoints"><spanclass="std std-ref">Public Entrypoint</span></a>. By <aclass="reference internal"href="interfaces.html#interfaces-discoverable"><spanclass="std std-ref">publishing your interface as discoverable</span></a>, you provide a potential connection point for others, helping the network grow and reach new areas.</p>
<p>For guidelines on how to properly configure and secure a public gateway, refer to the <aclass="reference internal"href="#hosting-entrypoints"><spanclass="std std-ref">Hosting Public Entrypoints</span></a> section.</p>
<h2>Connect to the Public Testnet<aclass="headerlink"href="#connect-to-the-public-testnet"title="Link to this heading">¶</a></h2>
<p>An experimental public testnet has been made accessible by volunteers in the community. You
can find interface definitions for adding to your <codeclass="docutils literal notranslate"><spanclass="pre">.reticulum/config</span></code> file on the
<p>As development of Reticulum has transitioned away from the public Internet, and is now happening exclusively over Reticulum itself, the lists on the <aclass="reference external"href="https://reticulum.network/connect.html">Reticulum Website</a> and the
<aclass="reference external"href="https://github.com/markqvist/Reticulum/wiki/Community-Node-List">Community Wiki</a> are no longer actively maintained, and any up-to-date connectivity information will have to be found elsewhere.</p>
<p>For a while, these resources will likely still be a usable way to find bootstrap connections, that will allow you to discover other entrypoints to connect to, but it is highly recommended to also check community run projects like <aclass="reference external"href="https://rmap.world/">rmap.world</a>.</p>
<p>You can connect your devices or instances to one or more of these to gain access to any
Reticulum networks they are physically connected to. Simply add one or more interface
snippets to your config file in the <codeclass="docutils literal notranslate"><spanclass="pre">[interface]</span></code> section, like in the example below:</p>
<p>Don’t rely on a single connection to a testnet entrypoint for everyday use. The testnet is often used for development and failure testing scenarios. Instead, read the <aclass="reference internal"href="#bootstrapping-connectivity"><spanclass="std std-ref">Bootstrapping Connectivity</span></a> section.</p>
<p>As the amount of global Reticulum nodes and entrypoints have grown to a substantial quantity, the public Amsterdam Testnet entrypoint is slated for de-commisioning in the first quarter of 2026. If your own instances rely on this entrypoint for connectivity, it is high time to start configuring alternatives. Read the <aclass="reference internal"href="#bootstrapping-connectivity"><spanclass="std std-ref">Bootstrapping Connectivity</span></a> section for pointers.</p>
<spanid="hosting-entrypoints"></span><h2>Hosting Public Entrypoints<aclass="headerlink"href="#hosting-public-entrypoints"title="Link to this heading">¶</a></h2>
Internet, this section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to <aclass="reference internal"href="interfaces.html#interfaces-discoverable"><spanclass="std std-ref">make it discoverable over Reticulum</span></a>.</p>
virtual with a public IP address, that can be reached by other devices on the Internet.</p>
<p>The most efficient and performant way to host a connectable entry-point supporting many
users is to use the <codeclass="docutils literal notranslate"><spanclass="pre">BackboneInterface</span></code>. This interface type is fully compatible with
the <codeclass="docutils literal notranslate"><spanclass="pre">TCPClientInterface</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">TCPServerInterface</span></code> types, but much faster and uses
less system resources, allowing your device to handle thousands of connections even on
small systems.</p>
<p>It is also important to set your connectable interface to <codeclass="docutils literal notranslate"><spanclass="pre">gateway</span></code> mode, since this
will greatly improve network convergence time and path resolution for anyone connecting
to your entry-point.</p>
<divclass="highlight-ini notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># This example demonstrates a backbone interface</span>
<spanclass="c1"># configured for acting as a gateway for users to</span>
<spanclass="c1"># connect to either a public or private network</span>
<p>If instead you want to make a private entry-point from the Internet, you can use the
<aclass="reference internal"href="interfaces.html#interfaces-options"><spanclass="std std-ref">IFAC name and passphrase options</span></a> to secure your interface with a network name and passphrase.</p>
<divclass="highlight-ini notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># A private entry-point requiring a pre-shared</span>
<spanclass="c1"># network name and passphrase to connect to.</span>
<p>If you are hosting an entry-point on an operating system that does not support
<codeclass="docutils literal notranslate"><spanclass="pre">BackboneInterface</span></code>, you can use <codeclass="docutils literal notranslate"><spanclass="pre">TCPServerInterface</span></code> instead, although it will
<p>Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. Reticulum supports a wide range of radio
hardware, and if you already have any available, it is very likely that it will
work with Reticulum. For information on how to configure this, see the
<aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="std std-ref">Interfaces</span></a> section of this manual.</p>
<p>If you do not already have transceiver hardware available, you can easily and
cheaply build an <aclass="reference internal"href="hardware.html#rnode-main"><spanclass="std std-ref">RNode</span></a>, which is a general-purpose long-range
digital radio transceiver, that integrates easily with Reticulum.</p>
<p>To build one yourself requires installing a custom firmware on a supported LoRa
development board with an auto-install script. Please see the <aclass="reference internal"href="hardware.html#hardware-main"><spanclass="std std-ref">Communications Hardware</span></a>
chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
<spanclass="xref std std-ref">list of suppliers</span>. For more information on RNode, you can also
refer to these additional external resources:</p>
<ulclass="simple">
<li><p><aclass="reference external"href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
<li><p><aclass="reference external"href="https://unsigned.io/installing-rnode-firmware-on-supported-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
<li><p><aclass="reference external"href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li>
<p>If you have communications hardware that is not already supported by any of the
<aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="std std-ref">existing interface types</span></a>, but you think would be suitable for use with Reticulum,
you are welcome to head over to the <aclass="reference external"href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
and propose adding an interface for the hardware.</p>
<p>The above command will install Reticulum and dependencies, and you will be
ready to import and use RNS in your own programs. The next step will most
likely be to look at some <aclass="reference internal"href="examples.html#examples-main"><spanclass="std std-ref">Example Programs</span></a>.</p>
<p>The entire Reticulum API is documented in the <aclass="reference internal"href="reference.html#api-main"><spanclass="std std-ref">API Reference</span></a>
chapter of this manual. Before diving in, it’s probably a good idea to read
this manual in full, but at least start with the <aclass="reference internal"href="understanding.html#understanding-main"><spanclass="std std-ref">Understanding Reticulum</span></a> chapter.</p>
<spanid="install-guides"></span><h2>Platform-Specific Install Notes<aclass="headerlink"href="#platform-specific-install-notes"title="Link to this heading">¶</a></h2>
<p>Termux is a terminal emulator and Linux environment for Android based devices,
which includes the ability to use many different programs and libraries,
including Reticulum.</p>
<p>To use Reticulum within the Termux environment, you will need to install
<codeclass="docutils literal notranslate"><spanclass="pre">python</span></code> and the <codeclass="docutils literal notranslate"><spanclass="pre">python-cryptography</span></code> library using <codeclass="docutils literal notranslate"><spanclass="pre">pkg</span></code>, the package-manager
build into Termux. After that, you can use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install Reticulum.</p>
<divclass="highlight-shell notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># First, make sure indexes and packages are up to date.</span>
<divclass="highlight-shell notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># First, make sure indexes and packages are up to date.</span>
<p>It is also possible to include Reticulum in apps compiled and distributed as
Android APKs. A detailed tutorial and example source code will be included
here at a later point. Until then you can use the <aclass="reference external"href="https://github.com/markqvist/sideband">Sideband source code</a> as an example and starting point.</p>
<p>On some architectures, including ARM64, not all dependencies have precompiled
binaries. On such systems, you may need to install <codeclass="docutils literal notranslate"><spanclass="pre">python3-dev</span></code> (or similar) before
installing Reticulum or programs that depend on Reticulum.</p>
<p>With these packages installed, <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> will be able to build any missing dependencies
<p>On versions of Debian released after April 2023, it is no longer possible by default
to use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
use the replacement <codeclass="docutils literal notranslate"><spanclass="pre">pipx</span></code> command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but will not work
for including and using Reticulum in your own scripts and programs.</p>
<p>Alternatively, you can restore normal behaviour to <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> by creating or editing
the configuration file located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/pip/pip.conf</span></code>, and adding the
<p>For a one-shot installation of Reticulum, without globally enabling the <codeclass="docutils literal notranslate"><spanclass="pre">break-system-packages</span></code>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
cases lead to version conflicts, it does not generally pose any problems, especially
<p>To install Reticulum on macOS, you will need to have Python and the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> package
manager installed.</p>
<p>Systems running macOS can vary quite widely in whether or not Python is pre-installed,
and if it is, which version is installed, and whether the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> package manager is
also installed and set up. If in doubt, you can <aclass="reference external"href="https://www.python.org/downloads/">download and install</a>
Python manually.</p>
<p>When Python and <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> is available on your system, simply open a terminal window
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.</p>
</div>
<p>Additionally, some version combinations of macOS and Python require you to
manually add your installed <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment
variable, before you can use installed commands in your terminal. Usually, adding
the following line to your shell init script (for example <codeclass="docutils literal notranslate"><spanclass="pre">~/.zshrc</span></code>) will be enough:</p>
<p>On OpenWRT systems with sufficient storage and memory, you can install
Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>At the time of releasing this manual, work is underway to create pre-built
Reticulum packages for OpenWRT, with full configuration, service
and <codeclass="docutils literal notranslate"><spanclass="pre">uci</span></code> integration. Please see the <aclass="reference external"href="https://github.com/gretel/feed-reticulum">feed-reticulum</a>
and <aclass="reference external"href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a>
repositories for more information.</p>
</div>
<p>To install Reticulum on OpenWRT, first log into a command line session, and
<p>The above instructions have been verified and tested on OpenWRT 21.02 only.
It is likely that other versions may require slightly altered installation
commands or package names. You will also need enough free space in your
overlay FS, and enough free RAM to actually run Reticulum and any related
programs and utilities.</p>
</div>
<p>Depending on your device configuration, you may need to adjust firewall rules
for Reticulum connectivity to and from your device to work. Until proper
packaging is ready, you will also need to manually create a service or startup
script to automatically laucnh Reticulum at boot time.</p>
<p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses
to be enabled for any Ethernet and WiFi devices you intend to use. If <codeclass="docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">a</span></code>
shows an address starting with <codeclass="docutils literal notranslate"><spanclass="pre">fe80::</span></code> for the device in question,
<codeclass="docutils literal notranslate"><spanclass="pre">AutoInterface</span></code> should work for that device.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.</p>
</div>
<p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
it will require manually configuring and installing required build dependencies,
<p>On some architectures, including RISC-V, not all dependencies have precompiled
binaries. On such systems, you may need to install <codeclass="docutils literal notranslate"><spanclass="pre">python3-dev</span></code> (or similar) before
installing Reticulum or programs that depend on Reticulum.</p>
<p>With these packages installed, <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> will be able to build any missing dependencies
<p>On versions of Ubuntu released after April 2023, it is no longer possible by default
to use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
use the replacement <codeclass="docutils literal notranslate"><spanclass="pre">pipx</span></code> command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but will not work
for including and using Reticulum in your own scripts and programs.</p>
<p>Alternatively, you can restore normal behaviour to <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> by creating or editing
the configuration file located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/pip/pip.conf</span></code>, and adding the
<p>For a one-shot installation of Reticulum, without globally enabling the <codeclass="docutils literal notranslate"><spanclass="pre">break-system-packages</span></code>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
cases lead to version conflicts, it does not generally pose any problems, especially
<p>On Windows operating systems, the easiest way to install Reticulum is by using the
<codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> package manager from the command line (either the command prompt or Windows
Powershell).</p>
<p>If you don’t already have Python installed, <aclass="reference external"href="https://www.python.org/downloads/">download and install Python</a>.
At the time of publication of this manual, the recommended version is <aclass="reference external"href="https://www.python.org/downloads/release/python-3127">Python 3.12.7</a>.</p>
<p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to
your PATH environment variables. If you don’t do this, you will not be able to
use the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as
<codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code>) from the command line.</p>
<p>After installing Python, open the command prompt or Windows Powershell, and type:</p>
<p>If you use the <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> package to run Reticulum on systems that
do not support <aclass="reference external"href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is
important that you read and understand the <aclass="reference internal"href="understanding.html#understanding-primitives"><spanclass="std std-ref">Cryptographic Primitives</span></a>
section of this manual.</p>
</div>
<p>In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies. In such situations,
you can use the <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> package instead of the <codeclass="docutils literal notranslate"><spanclass="pre">rns</span></code> package, or use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>
with the <codeclass="docutils literal notranslate"><spanclass="pre">--no-dependencies</span></code> command-line option. The <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code>
package requires no external dependencies for installation. Please note that the
actual contents of the <codeclass="docutils literal notranslate"><spanclass="pre">rns</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> packages are <em>completely identical</em>.
The only difference is that the <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> package lists no dependencies required
for installation.</p>
<p>No matter how Reticulum is installed and started, it will load external dependencies
only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum
on a system that cannot support <codeclass="docutils literal notranslate"><spanclass="pre">pyserial</span></code>, it is perfectly possible to do so using
the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces.
All other available modules will still be loaded when needed.</p>
</section>
</section>
</article>
</div>
<footer>
<divclass="related-pages">
<aclass="next-page"href="using.html">
<divclass="page-info">
<divclass="context">
<span>Next</span>
</div>
<divclass="title">Using Reticulum on Your System</div>
