Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Files and Environment

The state directory

rex-iroh keeps everything it remembers in one directory per device:

PlatformDefault location
Linux$XDG_DATA_HOME/rex-iroh, usually ~/.local/share/rex-iroh
macOS~/Library/Application Support/rex-iroh

Set REX_IROH_DIR or pass --state-dir to use a different one. Two state directories on one machine act as two separate devices, each with its own key.

FileWhat it holds
secret.keyThis device’s private key. Its public half is the device’s endpoint id.
allowlistThe devices allowed to connect to this one.
allowlist.bakThe last allowlist that parsed, which serve falls back on.
peers/The tickets of issuers this device has joined, one file each, named after it.
sockets/Each joined issuer’s socket for connect, named after it and this device.
control.sockThe socket pair and peers use to talk to a running serve.

The key is created the first time any command runs. Anyone with a copy of secret.key can act as this device, so rex-iroh creates it readable only by you, and refuses to start if any other user has any access to it. Deleting it gives the device a new identity, and every issuer it was paired with will turn it away until it pairs again.

Environment variables

REX_IROH_DIR
The state directory, as with --state-dir.
REX_SERVER
The Rex server serve forwards to, as with --rex-server. Rex sets this in its own terminals and reads it too, so inside a Rex terminal serve uses the server that terminal belongs to.
RUST_LOG
How much to log, as a tracing filter. The default, rex_iroh=info, logs each connection that’s accepted or refused and the outcome of each pairing. rex_iroh=debug adds why each connection ended.

How serve finds Rex

Without --rex-server or REX_SERVER, serve looks for a Rex server in this order and uses the first one it finds:

  1. The socket reported by rex whoami, using the rex on your PATH. If that rex turns out to be some other program with the same name, it’s skipped. If it is Rex but can’t name a socket, serve goes straight to step 3.
  2. The socket reported by rex whoami, using a rex binary in one of the places Rex’s installers put it:
    • Linux: /usr/bin/rex, /usr/local/bin/rex, ~/.local/bin/rex
    • macOS: inside the Rex app’s support directory, ~/Library/Application Support/com.superlogical.rex/RexServer/Versions/Current/Rex Server.app/Contents/MacOS/rex
    • Either: ~/.nix-profile/bin/rex, /run/current-system/sw/bin/rex
  3. Rex’s default socket, if a server is listening on it:
    • Linux: $XDG_STATE_HOME/rex/run/server.sock, usually ~/.local/state/rex/run/server.sock
    • macOS: ~/Library/Application Support/rex/server.sock

Looking never starts a Rex server. Whichever socket it picks, serve checks that a server is listening there before going any further.