What you need

  • A Mac with macOS 11 (Big Sur) or newer. Macs with Apple’s own chips (M1 and later) are tested. Macs with an Intel processor should work, but nobody has tried one yet.
  • Your normal account. Do not use sudo to run the installer.
  • An internet connection for the install only (it downloads the software once). Using the network afterwards does not need one.

Nothing else. The installer brings its own copy of Python, so it does not touch the one on your Mac.

Steps

  1. Open Terminal. It is in Applications → Utilities, or press ⌘ Space, type Terminal and press Return.

  2. Copy this whole line, paste it into Terminal, and press Return:

    curl -fsSL https://codeberg.org/permanet/rns-installer/releases/download/v0.1.8/rns-installer-macos.sh | bash

    This downloads the installer, checks that the download is complete and unchanged, and starts it.

  3. Answer the questions. Press Return to accept the answer shown in brackets.

    QuestionWhat to answer
    Carry traffic for other people’s devices?No for a laptop. Yes only for a Mac that stays on and logged in, which helps the network.
    Go online now?No is fine. You can switch later: see Going online on a Mac.

  4. The installer shows a plan of everything it will do. Read it. Type y and press Return to go ahead, or n to stop.

  5. If it asks for your password, type the password you use to log in to this Mac and press Return. The letters do not appear while you type. That is normal. See The firewall for why it may ask.

  6. It finishes by checking that Reticulum runs and prints its status. You should see a line with Status : Up and, after a few minutes, other devices listed under your local network.

Reticulum now starts by itself whenever you log in. It only runs while you are logged in. macOS shows a notice, App Background Activity: “python” can run in the background. That is Reticulum. Leave it allowed.

If you stop at the plan, nothing is set up, but the downloaded installer stays in ~/.local/share/permanet-rns-installer. You can delete that folder.

The firewall

The macOS firewall is off on a new Mac. If you turned it on, it silently blocks other devices from reaching Reticulum, so no one on your network shows up. The plan tells you when this is the case, and the installer adds a rule that lets Reticulum’s Python through. That is why it asks for your password.

If your account is not an administrator (a “Standard” account, see System Settings → Users & Groups), the installer cannot change the firewall. It prints two commands that start with sudo /usr/libexec/ApplicationFirewall/socketfilterfw. Ask the person with the administrator account to log in to their account, open Terminal there, and run both commands. Reticulum picks up the change by itself within a minute or two. Nothing needs restarting.

Open MeshChatX

Open MeshChatX from the Applications folder in your home folder (in Finder: Go → Home → Applications), or press ⌘ Space and type MeshChatX. You can also type meshchat in Terminal.

MeshChatX opens in your web browser. The page comes from your own Mac, and other computers cannot open it. To stop it: meshchat --stop.

On a Mac with an Intel processor the installer sets up MeshChat instead, the app MeshChatX is based on (MeshChatX needs a part that isn’t available for Intel Macs). It works the same way, without chat rooms; where these guides say MeshChatX, read MeshChat.

What you will see there, and how to check that everything runs, is on First run.

Going online on a Mac

Going online works the same as on Linux, with the command permanet-rns --online: see Going online. On a Mac, the I2P router (i2pd) comes from Homebrew, the usual tool for installing software on macOS:

  • If your Mac does not have Homebrew yet, the installer installs it first, with Homebrew’s own installer. That installer asks for your password, then says Press RETURN/ENTER to continue. Press Return.
  • It may then download Apple’s Command Line Tools. This is a large download and can take 10 minutes or more.
  • At the end Homebrew lists Next steps for adding it to your shell. You can skip them: the installer finds Homebrew by itself.
  • Homebrew’s usage reports are turned off.
  • macOS shows a notice that “i2pd” can run in the background. Leave it allowed.
  • If the firewall is on, macOS asks whether i2pd may accept incoming network connections. Click Allow.

Homebrew needs an administrator account. On a Standard account, the installer stops and says so. An administrator can install Homebrew and i2pd first (brew install i2pd), and then the installer uses that i2pd.

Download it yourself instead

If you prefer to look at the files before anything runs:

  1. Download the release and its checksum into one folder.

  2. Open Terminal in that folder and check the download. It should say OK:

    shasum -a 256 -c rns-installer-0.1.8.tar.gz.sha256

  3. Unpack it and see the plan. This changes nothing:

    tar xf rns-installer-0.1.8.tar.gz
cd rns-installer-0.1.8/installers/macos
bash install.sh --dry-run

  4. Run bash install.sh to install. Keep the folder, because permanet-rns runs the installer from it.

The source code is at codeberg.org/permanet.

What it changes

Everything lives in your own account. The installer only asks for your password when it needs to change something outside it, and it shows each one in the plan first:

  • the firewall rule, if the firewall is on,
  • Homebrew and i2pd, when you go online.
WhereWhat
~/.local/share/permanet-rns/The software (with its own Python), MeshChatX, logs and your answers
~/.local/share/permanet-rns-installer/The installer, used by permanet-rns
~/.local/bin/Commands such as meshchat, rnstatus, nomadnet and permanet-rns
~/Applications/MeshChatX.appOpens MeshChatX in your browser
~/.reticulum/Your Reticulum settings and identity
~/.meshchat/Your MeshChatX identity (kept here, where earlier MeshChat installs put it)
~/.meshchatx/MeshChatX’s messages and settings
~/Library/LaunchAgents/Starts Reticulum (and i2pd, when online) when you log in
~/.zshrcOne line, so new Terminal windows find the commands

If you already have a Reticulum setup, the installer keeps a copy of the old settings next to the new ones (a file named config.backup- followed by the date). It will not run while another program, such as MeshChatX or Sideband, is already running Reticulum: quit it first, then run the installer again.

Uninstall 

permanet-rns --uninstall

This removes everything in the table above except your identity and messages, and removes the firewall rule (it asks for your password, or on a Standard account prints the command for an administrator). What stays, and how to delete it for good, is on Uninstall. Homebrew and i2pd stay installed. To remove i2pd: brew uninstall i2pd.

If something does not work

A command is “not found”. Open a new Terminal window. Only new windows read the line the installer added. If that does not help, use the full path, for example ~/.local/bin/rnstatus.

No other devices show up. Give it a few minutes. Check that both devices are on the same network and that a VPN is off. If the firewall is on, check that Reticulum is allowed through it:

/usr/libexec/ApplicationFirewall/socketfilterfw --listapps

Look for a line ending in permanet-rns/python/bin/python3.13, followed by Allow incoming connections. If it says Block, or the line is missing, run the installer again (permanet-rns --offline, or --online if you are online) and it adds the rule.

Restart Reticulum. This stops MeshChatX, restarts Reticulum, and opens MeshChatX again:

meshchat --stop
launchctl kickstart -k gui/$(id -u)/xyz.permanet.rnsd
meshchat

The I2P links stay down. Wait up to 10 minutes the first time. Then restart i2pd:

launchctl kickstart -k gui/$(id -u)/xyz.permanet.i2pd

Logs are in ~/.local/share/permanet-rns/logs/ (rnsd.log, meshchat.log, i2pd.log), and Reticulum’s own log is ~/.reticulum/logfile. Logs can contain the addresses of nodes you talked to. Check what is in them before you share them with anyone.

More: Troubleshooting.

Next

First run.