LXMF-rs Monorepo

Rust monorepo for LXMF and Reticulum with strict library/app boundaries and enterprise quality gates.

Start Here

Contributor workflow: CONTRIBUTING.md
Current status and execution order: docs/status/current-roadmap.md
Docs map and retention rules: docs/README.md
SDK guide: docs/sdk/README.md
Support policy: docs/contracts/support-policy.md

Workspace Layout

LXMF-rs/
├── crates/
│   ├── libs/
│   │   ├── lxmf/
│   │   ├── lxmf-core/
│   │   ├── lxmf-sdk/
│   │   ├── reticulum-rs/
│   │   ├── rns-core/
│   │   ├── rns-embedded-core/
│   │   ├── rns-embedded-ffi/
│   │   ├── rns-embedded-runtime/
│   │   ├── rns-transport/
│   │   ├── rns-rpc/
│   │   └── test-support/
│   ├── apps/
│   │   ├── lxmf-cli/
│   │   ├── reticulumd/
│   │   └── rns-tools/
│   └── internal/
│       └── legacy crates kept outside the workspace
├── docs/
    ├── adr/
    ├── architecture/
    ├── contracts/
    ├── fixtures/
    ├── migrations/
    ├── runbooks/
    ├── schemas/
    └── sdk/
├── examples/
├── tools/
│   └── scripts/
├── scripts/
├── xtask/
└── wrappers/

Cargo.toml is the source of truth for active workspace members. Some crate directories are intentionally present on disk but excluded from the workspace.

Active Libraries

lxmf-wire (crates/libs/lxmf-core): message/payload/identity primitives.
lxmf: umbrella crate for lxmf-sdk and lxmf-wire.
lxmf-sdk: host-facing client API (start/send/cancel/status/configure/poll/snapshot/shutdown).
rns-embedded-runtime: node-centric embedded runtime facade with lifecycle, event, and managed std driver support.
rns-embedded-ffi: C ABI for embedded/manual-tick compatibility and the v1 node-centric API.
rns-embedded-core: shared embedded/runtime types and fixtures.
reticulum-rs: umbrella crate for the Reticulum stack crates.
reticulum-rs-core (crates/libs/rns-core): Reticulum cryptographic and packet primitives.
reticulum-rs-transport (crates/libs/rns-transport): transport + iface + receipt/resource API.
reticulum-rs-rpc (crates/libs/rns-rpc): JSON-RPC request/response/event contracts and bridges.
test-support: schema/fixture validation and integration-test helpers.

Published crates.io entry points:

lxmf
lxmf-sdk
lxmf-wire
reticulum-rs
reticulum-rs-core
reticulum-rs-transport
reticulum-rs-rpc

Published Crates

Main entry points:

lxmf (docs.rs): umbrella crate for LXMF wire types and the high-level SDK.
reticulum-rs (docs.rs): umbrella crate for the Reticulum stack crates.

Component crates:

lxmf-sdk (docs.rs): high-level Rust SDK for LXMF clients.
lxmf-wire (docs.rs): LXMF wire format, message primitives, and identity helpers.
reticulum-rs-core (docs.rs): core Reticulum cryptographic and packet primitives.
reticulum-rs-transport (docs.rs): transport, interface, receipt, and resource layers.
reticulum-rs-rpc (docs.rs): JSON-RPC request, response, event, and daemon bridge contracts.

Active Applications

lxmf-cli
reticulumd
rns-tools

Bootstrap

Recommended:

make bootstrap

Direct script form:

./tools/scripts/bootstrap-dev.sh

Verification-only mode:

./tools/scripts/bootstrap-dev.sh --check --skip-smoke

Build and Validation

cargo check --workspace --all-targets
cargo test --workspace
cargo clippy --workspace --all-targets --all-features --no-deps -- -D warnings
cargo doc --workspace --no-deps
./tools/scripts/check-boundaries.sh

or via xtask:

cargo xtask ci
cargo xtask release-check
cargo xtask package-daemon-bundle --version 0.1
cargo xtask api-diff
cargo xtask python-impl-bench-compare
cargo xtask python-impl-bench-compare --profile report
cargo xtask python-impl-bench-report

For fast local iteration on one binary, prefer narrow commands:

make check-bin PKG=lxmf-cli BIN=lxmd
make run-bin PKG=rns-tools BIN=rnsd ARGS="--help"
make package-daemon-bundle VERSION=0.1
make python-lxmd-smoke

Binaries

lxmf-cli
lxmd
reticulumd
rncp, rnid, rnir, rnodeconf, rnpath, rnpkg, rnprobe, rnsd, rnstatus, rnx

Run examples:

cargo run -p lxmf-cli -- --help
cargo run -p reticulumd -- --help
cargo run -p rns-tools --bin rnx -- e2e --timeout-secs 20

Documentation Entry Points

Docs map: docs/README.md
Current status: docs/status/current-roadmap.md
API surface and stability: docs/lxmf-rs-api.md
CLI quick reference: docs/lxmf-cli.md
Architecture overview: docs/architecture/overview.md
JSON and wire-field mapping: docs/architecture/json-lxmf-fields.md
Compatibility contract: docs/contracts/compatibility-contract.md
Compatibility matrix: docs/contracts/compatibility-matrix.md
Third-party compatibility kit: docs/contracts/third-party-compatibility-kit.md
Support and LTS policy: docs/contracts/support-policy.md
Extension registry: docs/contracts/extension-registry.md
RPC contract: docs/contracts/rpc-contract.md
Payload contract: docs/contracts/payload-contract.md
crates.io publish plan: docs/runbooks/crates-io-publish-plan.md
Release readiness: docs/runbooks/release-readiness.md

crates.io Consumers

For library consumers, prefer the published package names rather than the workspace directory names:

[dependencies]
lxmf = "0.3.0"
reticulum-rs = "0.2.0"

Or depend on the component crates directly:

[dependencies]
lxmf-sdk = "0.2.1"
reticulum-rs-rpc = "0.3.0"

SDK Guide

Guide index: docs/sdk/README.md
Quickstart: docs/sdk/quickstart.md
Profiles/configuration: docs/sdk/configuration-profiles.md
Config cookbook: docs/runbooks/sdk-config-cookbook.md
Lifecycle/events: docs/sdk/lifecycle-and-events.md
Advanced embedding: docs/sdk/advanced-embedding.md

Release Bundles

cargo xtask package-daemon-bundle builds the host-native lxmd and reticulumd binaries, generates lxmd.example.config, copies README.md, and writes a release archive under target/release-bundles/. The command emits .zip bundles on Windows and .tar.gz bundles on macOS/Linux.

On macOS, Gatekeeper may quarantine a downloaded release bundle because the project does not currently ship signed/notarized binaries. If that happens, remove the quarantine attribute after extracting the archive:

xattr -dr com.apple.quarantine /path/to/lxmd-daemon-<version>-macos-arm64
chmod +x /path/to/lxmd-daemon-<version>-macos-arm64/lxmd
chmod +x /path/to/lxmd-daemon-<version>-macos-arm64/reticulumd

Embedded Node FFI

Header: crates/libs/rns-embedded-ffi/include/rns_embedded_ffi.h
Guide and example: crates/libs/rns-embedded-ffi/README.md
Stable core contract: lifecycle, status, capability probe, send/broadcast, subscriptions, structured errors
Compatibility surface: legacy manual tick, raw wire ingress/egress, low-level queueing
Extension surface: numeric extension IDs validated by docs/fixtures/embedded/public-node-api-v1/extension-ids.json
v1 node-centric API: rns_embedded_v1_node_new/start/stop/restart/get_status/send/broadcast/set_log_level/subscribe_events
legacy compatibility API remains available for manual tick, raw wire ingress/egress, and low-level queueing

Governance

Security policy: SECURITY.md
Code ownership: .github/CODEOWNERS

Linux daemon setup (systemd)

The following installs a long-running lxmd service. lxmd also launches reticulumd, so a single unit is enough for most deployments.

Install binaries (from source)

cargo build --release -p lxmf-cli -p reticulumd
sudo install -m 0755 target/release/lxmd /usr/local/bin/lxmd
sudo install -m 0755 target/release/reticulumd /usr/local/bin/reticulumd

Create a dedicated service user and daemon directories

sudo useradd --system --create-home --shell /usr/sbin/nologin lxmd
sudo mkdir -p /etc/lxmf/lxmd /etc/lxmf/reticulumd /var/log/lxmf
sudo chown -R lxmd:lxmd /etc/lxmf /var/log/lxmf

Create a starting config file for lxmd

sudo mkdir -p /etc/lxmf/lxmd
sudo chown lxmd:lxmd /etc/lxmf/lxmd
sudo -u lxmd /usr/local/bin/lxmd --exampleconfig > /etc/lxmf/lxmd/config
sudo chmod 600 /etc/lxmf/lxmd/config

Optional: set an explicit Reticulum config for reticulumd (instead of relying on generated defaults).

sudo cp crates/apps/reticulumd/examples/service-reference.toml /etc/lxmf/reticulumd/config.toml
sudo chown lxmd:lxmd /etc/lxmf/reticulumd/config.toml

Install a systemd unit for the daemon

sudo tee /etc/systemd/system/lxmd.service > /dev/null <<'EOF'
[Unit]
Description=LXMF daemon (lxmd + reticulumd)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=lxmd
Group=lxmd
WorkingDirectory=/etc/lxmf/lxmd
ExecStart=/usr/local/bin/lxmd --config /etc/lxmf/lxmd/config --rnsconfig /etc/lxmf/reticulumd/config.toml
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target
EOF

If you are not using /etc/lxmf/reticulumd/config.toml, remove --rnsconfig /etc/lxmf/reticulumd/config.toml from ExecStart and run only with --config.

Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable --now lxmd.service
sudo systemctl status lxmd.service --no-pager

Tail logs and verify health

sudo journalctl -u lxmd.service -f

Using the official GitHub release binaries

Latest release artifacts are published at:

https://github.com/FreeTAKTeam/LXMF-rs/releases

Open the release page and download the package for your platform.
Linux/macOS

tar -xzf lxmd-daemon-<version>-linux-amd64.tar.gz
tar -xzf lxmd-daemon-<version>-macos-arm64.tar.gz

Windows

Expand-Archive lxmd-daemon-<version>-windows-x86_64.zip .

Run directly for validation

./lxmd --help
./reticulumd --help

Generate a starter lxmd config and follow the same daemon setup flow as above

./lxmd --exampleconfig > /tmp/lxmd.config

If you are using Linux and the Linux daemon guide above, point --config at the downloaded config file and keep binaries in place via your package manager path or your custom install path.

Notes

If sccache is installed and you want to use it, set RUSTC_WRAPPER=sccache before building.
Cross-language benchmark configuration lives in tools/benchmarks/python_impl.toml, and the operating runbook is docs/runbooks/python-impl-benchmarking.md.
For daemon-level mixed-runtime smoke coverage, make python-lxmd-smoke launches a Rust lxmd node and an installed Python lxmd node together.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 584 Commits
.cargo		.cargo
.github		.github
crates		crates
docs		docs
generated/clients/spec		generated/clients/spec
scripts		scripts
tools		tools
wrappers/flutter		wrappers/flutter
xtask		xtask
.editorconfig		.editorconfig
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
clippy.toml		clippy.toml
deny.toml		deny.toml
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

LXMF-rs Monorepo

Start Here

Workspace Layout

Active Libraries

Published Crates

Active Applications

Bootstrap

Build and Validation

Binaries

Documentation Entry Points

crates.io Consumers

SDK Guide

Release Bundles

Embedded Node FFI

Governance

Linux daemon setup (systemd)

Using the official GitHub release binaries

Notes

License

About

Uh oh!

Releases 5

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

LXMF-rs Monorepo

Start Here

Workspace Layout

Active Libraries

Published Crates

Active Applications

Bootstrap

Build and Validation

Binaries

Documentation Entry Points

crates.io Consumers

SDK Guide

Release Bundles

Embedded Node FFI

Governance

Linux daemon setup (systemd)

Using the official GitHub release binaries

Notes

License

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages