stigmerge

stigmerge (distribution and transfer) sends and receives file content anonymously over the Veilid network.

Usage

stigmerge seed <file> indexes and seeds a file, displaying the dht key which can be used to fetch it.

stigmerge fetch <dht key> [directory] fetches a file while it's being seeded (defaults to current directory).

Similar to bittorrent, stigmerge cannot fetch a file unless it's being seeded by a peer.

See stigmerge --help for more options.

Try it!

Try fetching a test file with stigmerge fetch VLD0:yb7Mz4g-BaFzn2qDt-xCPzsbzlJz7iq1MOFFBaCXqTw.

Install

Install a binary release on Linux, macOS or Windows.

Rust crate

Build and install from crates.io with cargo install stigmerge.

Crate dependencies may require system packages to be installed depending on the target platform.

Debian Bookworm needs apt-get install build-essential libssl-dev pkg-config.

Others may be similar.

Nix flake

Run stigmerge on Nix with nix run github:cmars/stigmerge.

Add this flake (github:cmars/stigmerge) as an input to your home manager flake.

Or add the default package to a legacy home.nix with something like:

(builtins.getFlake "github:cmars/stigmerge").packages.x86_64-linux.default

Android (termux binary)

Stigmerge can be compiled from source and run on the command-line with Termux on Android.

You'll need to install Rust and Cargo to build it, and the following runtime dependencies:

pkg install which
pkg install openjdk-21

Other JDKs might work as well, YMMV. Comments in stigmerge/src/bin/stigmerge.rs explain why this is currently necessary.

Plans

What's on the roadmap for a 1.0 release.

Trackers

Trackers will enable a swarm of stigmerge peers to operate more like bittorrent, where blocks may be simultaneously seeded and fetched.

Multi-file shares

The stigmerge wire protocol and indexing structures support multi-file shares, but this hasn't been fully implemented yet.

Troubleshooting

Clock skew

stigmerge operates an embedded Veilid node, which requires a synchronized local clock. Clock skew can prevent stigmerge from connecting to the Veilid network.

Debug logging

Logging can be configured with the RUST_LOG environment variable.

RUST_LOG=debug will enable all debug-level logging in stigmerge as well as veilid-core, which may be useful for troubleshooting low-level Veilid network problems and reporting issues.

Issues

When opening an issue, note the OS type, OS release version, stigmerge version, and steps to reproduce. Any logs you can attach may help.

Development

In a Nix environment, nix develop github:cmars/stigmerge (or nix develop in this directory) to get a devshell with the necessary tool dependencies.

On other platforms a Veilid development environment will suffice.

capnp is only necessary when working on the protocol wire-format.

CICD

Github is used for CICD and especially release automation.

Contributions

Branches and releases are regularly mirrored to Gitlab. Pull requests might be accepted from either, if they fit with the project plans and goals.

Open an issue and ask before picking up a branch and proposing, for best results.