lxst-relay/AGENTS.md

Development Notes for lxst-relay

Quick start

# Run as script or directly (if executable)
python lxst_relay.py --help

# Run with custom config directory
python lxst_relay.py --config /path/to/config

# Optional verbose output
python lxst_relay.py -v --config /path/to/config

Architecture

• Single-file Python app (lxst_relay.py) using CLI argparse
• No external dependencies beyond the script (imports RNS, LXMF from system/site)
• Each voice channel = its own Reticulum node with persistent identity
• Channels persisted to ${configdir}/channels/<name>/identity and admins file
• LXMF bot handles /create_channel <name> commands

Commands & arguments

Common:

• --config, -c : path to config directory (defaults to ~/.lxst-relay or /etc/lxst-relay)
• --rnsconfig : alternative Reticulum config directory
• --channel, -n : lobby channel name (default: "default")
• --version : show version and exit
• -v, --verbose : increase logging verbosity
• --announce_interval : seconds between network announces (0 = once at startup)

Operations

• Creating a channel: Send /create_channel <name> to the LXMF bot
• Listing channels: Send /channels or /channels_json to the bot
• Admins: Creator of each channel is its admin; admins stored in ${configdir}/channels/<name>/admins
• Identity: Stored in ${configdir}/identity; regenerated if missing

Gotchas

• Channel names cannot contain / or have adjacent directories (..)
• First run creates a new RNS identity in config dir
• Signal handlers (SIGINT, SIGTERM) properly clean up participants before exit
• No test framework; testing done manually via calls/messages or by inspecting logs
• Logs to RNS; use -v and/or --rnsconfig to control verbosity
• If --rnsconfig unset, RNS uses system-wide location; set explicitly on first run for reproducible setups

Project layout

lxst_relay.py       # Main application entrypoint
lxst-relay          # Executable wrapper (generated symlink or copy)
.git/               # Version control only
.gitignore          # Ignore patterns