# joinstr

> Self-hosted, open-source Bitcoin CoinJoin tool that runs mixing pools over nostr relays with no coordinator: web UI, REST daemon, CLI or Electrum plugin on your node.

- **Category:** [Cryptocurrency](https://selfhost.directory/cryptocurrency)
- **Licence:** mit
- **Source model:** Open source
- **Author:** invincible-privacy
- **Platforms:** Docker, Umbrel, Build from Source
- **Ports:** 8000 (joinstrd REST API)
- **Requires:** Tor, Bitcoin Core, Aut-ct daemon (optional), Electrum server (optional)
- **Tags:** Privacy, Anonymity, Tor, Electrum, Bitcoin, Nostr, Cryptocurrency

## What is joinstr?

joinstr mixes bitcoin coins without a trusted hub: peers announce pools on ordinary nostr relays, each member signs their own input early with SIGHASH_ALL|ANYONECANPAY, and everyone verifies and then relays the finished transaction. Each pool fixes one denomination and a peer count of 2 to 10, and coordination traffic runs over Tor using isolated circuits, which keeps a relay from linking inputs to outputs by IP. This GitLab repository ships the Python side of the ecosystem — an Electrum plugin, a Flask-based web UI, a command line client and joinstrd, a loopback-only daemon exposing a REST API documented at /docs, /redoc and /openapi.json. To self-host it you need Python 3, a Bitcoin Core node with RPC and a local Tor proxy; the container build under contrib/docker packages its own Tor and opens the interface at TCP 5000, and that same Flask app is what the Umbrel app store distributes. Optional aut-ct keyset pools help defend against sybil attackers. Android, Sparrow and Rust clients are maintained in separate repositories; versioning is pre-1.0 but mainnet use is documented.

## Should you self-host joinstr?

joinstr scores **53/100** on selfhost.directory ([how scoring works](https://selfhost.directory/scoring)) and ranks **#24 of 44** in [Cryptocurrency](https://selfhost.directory/cryptocurrency).

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is advanced: plan for several services and some ongoing maintenance. It is mit-licensed.

Its closest alternative on selfhost.directory is [Freqtrade](https://selfhost.directory/project/freqtrade) (87/100, 56 945 stars). It scores higher overall, so compare the two before you pick. [See joinstr vs Freqtrade side by side.](https://selfhost.directory/compare/freqtrade-vs-joinstr)

## Features

- CLI Client
- Custom pool denomination and peer count
- Hardware / air-gapped signing
- Nostr relay coordination
- OpenAPI documentation
- REST API daemon
- Resume interrupted pools
- Ring signature drop-out recovery
- Sybil resistance via aut-ct (◐ partial) — Supported in the Electrum plugin and Sparrow clients.
- Web UI

## How to install joinstr

### Install joinstr with Docker

Environment variables:

```
JOINSTR_MANAGED, BITCOIN_RPC_URL, BITCOIN_RPC_USER, BITCOIN_RPC_PASS, JOINSTR_WALLET
```

```
cd contrib/docker
docker build --build-arg JOINSTR_REF=$(git rev-parse HEAD) -t joinstr-web:dev .
docker run --rm -p 127.0.0.1:5000:5000 \
  -e JOINSTR_MANAGED=1 -e BITCOIN_RPC_URL=http://<node>:8332 \
  -e BITCOIN_RPC_USER=<user> -e BITCOIN_RPC_PASS=<password> \
  joinstr-web:dev
```

Note: The container build lives in contrib/docker; the image runs Tor inside the container and serves the web UI on port 5000.

### Install joinstr with Umbrel

- Install Bitcoin Node and then Joinstr from the Umbrel app store.
- Open Joinstr. It connects to your node by itself, starts its own Tor and uses a Bitcoin Core wallet named joinstr, which it creates on first start.

Note: One-click app at apps.umbrel.com/app/joinstr, version 0.1.2.

### Install joinstr with Build from Source

Environment variables:

```
BITCOIN_RPC_URL, BITCOIN_RPC_USER, BITCOIN_RPC_PASS, TOR_PROXY, JOINSTR_DATA_DIR, JOINSTRD_HOST, JOINSTRD_PORT
```

```
git clone https://gitlab.com/invincible-privacy/joinstr.git
cd joinstr
pip install -r gui/requirements.txt
python gui/joinstr-web.py --port 5000 --wallet <wallet_name>
```

Note: Daemon variant: pip install -r cli/requirements.txt, then python cli/joinstrd.py with config in ~/.joinstr/config.ini.

## FAQ

### Where can I ask questions?

On the joinstr forum at forum.joinstr.xyz; bugs go to the issue tracker of the client you use.

### Is there a fee for market makers?

No; joinstr currently has no makers and no coordinator fees.

### Can a pool creator steal my coins?

No — your client checks the full transaction before signing and broadcasting and refuses rounds costing more than 15000 sats or inputs that could be broadcast alone.

### What happens if a peer disappears in the middle of a round?

Before signing, the others can complete a smaller coinjoin via ring signature recovery; after signing nothing changes because every peer broadcasts the transaction.

### Is the old Riseup VPN option still there?

Yes, as an option in the Electrum plugin and the Android app; a VPN pool makes every peer use the same Riseup gateway, with Tor still the default.

### Do I need Tor?

Tor is the default and strongly recommended; the main clients refuse to reach a relay without it unless the pool uses the VPN transport.

### Which relay should I use?

Any nostr relay accepting kind 2022 and kind 4 events; the default is wss://nos.lol and paid relays reduce spam.

### How many peers should a pool have?

At least 2; more peers give a larger anonymity set but take longer to fill. The web UI allows 2 to 10.

### What does a coinjoin cost?

Only the shared mining fee plus the premium your coin holds over the denomination; there is no coordinator fee, though a paid relay may charge.

### Which denominations can I use?

Any — the pool creator chooses the denomination, and your coin must be worth that denomination plus 500 to 5000 sats since there is no change output.

### Do I need to run Bitcoin Core?

Not necessarily: the Electrum plugin (and Sparrow) work with an Electrum server, while the web UI, daemon and Android app need Bitcoin Core.

### Can I use joinstr on mainnet?

Yes; the Electrum plugin, web UI, daemon, Android app and Sparrow all work on mainnet, though a test round on Mutinynet or signet is suggested first.

## joinstr is a self-hosted alternative to

- [JoinMarket](https://selfhost.directory/alternative-to/joinmarket)
- [Wasabi Wallet (WabiSabi)](https://selfhost.directory/alternative-to/wasabi-wallet-wabisabi)
- [Whirlpool (Samourai)](https://selfhost.directory/alternative-to/whirlpool-samourai)

## joinstr alternatives

- [jam](https://selfhost.directory/project/jam): Self-hosted web interface for JoinMarket NG that makes CoinJoin privacy accessible with sensible defaults for beginners and advanced features for power users. (compare: https://selfhost.directory/compare/jam-vs-joinstr)
- [NNostr](https://selfhost.directory/project/nnostr): NNostr is a self-hosted, open-source Nostr relay and client library written in C# that supports paid events via BTCPay Server integration. (compare: https://selfhost.directory/compare/joinstr-vs-nnostr)
- [bitcoin-full-node-with-docker](https://selfhost.directory/project/bitcoin-full-node-with-docker): Self-hosted, open-source Docker stack running a Bitcoin full node with Electrs, block explorer, Tor, and optional I2P — all built locally from verified sources. (compare: https://selfhost.directory/compare/bitcoin-full-node-with-docker-vs-joinstr)
- [Nostr VPN](https://selfhost.directory/project/nostr-vpn): Self-hosted, open-source mesh VPN using Nostr identities for enrollment and Bitcoin-paid exit nodes. (compare: https://selfhost.directory/compare/joinstr-vs-nostr-vpn)
- [Shopstr](https://selfhost.directory/project/shopstr): Shopstr is a self-hosted, open-source Nostr marketplace enabling censorship-resistant Bitcoin commerce via Lightning and Cashu with no KYC or platform fees. (compare: https://selfhost.directory/compare/joinstr-vs-shopstr)
- [public-pool](https://selfhost.directory/project/public-pool): Self-hosted open-source Bitcoin stratum mining server built on NestJS; supports mainnet and testnet and pairs with the public-pool-ui web interface. (compare: https://selfhost.directory/compare/joinstr-vs-public-pool)
- [Spiral Pool](https://selfhost.directory/project/spiral-pool): Self-hosted solo mining pool for 16 cryptocurrencies supporting Stratum protocols, merge mining, and direct wallet payouts. (compare: https://selfhost.directory/compare/joinstr-vs-spiral-pool)
- [nostream](https://selfhost.directory/project/nostream): Own a relay for social network nobody can switch off (compare: https://selfhost.directory/compare/joinstr-vs-nostream)

## More in Cryptocurrency

- [Lightning Terminal](https://selfhost.directory/project/lightning-terminal): Lightning Terminal: Your Home for Lightning Liquidity
- [LNbits](https://selfhost.directory/project/lnbits): Open-source, self-hosted Bitcoin Lightning wallet accounts system with per-wallet API keys, LNURL and Nostr support, 50+ extensions, and LND or Core Lightning backends.
- [LND](https://selfhost.directory/project/lnd): Self-hosted, open-source implementation of a full Lightning Network node: open channels, route and send payments, with autopilot, watchtower and gRPC/REST APIs.
- [lndg](https://selfhost.directory/project/lndg): LNDg is a self-hosted, open-source web UI for Lightning Network node operators to analyze LND data and automate channel rebalancing, fee management, and peer monitoring.
- [machinaris](https://selfhost.directory/project/machinaris): Self-hosted WebUI for Chia plotting/farming bundling MadMax, Gigahorse, Bladebit, Plotman, and Chiadog in Docker with multi-blockchain support.
- [mempool](https://selfhost.directory/project/mempool): Open-source Bitcoin block explorer and mempool visualizer with fee estimates, mining and Lightning dashboards; self-host it via Docker or one-click node distros.
- [Mobazha](https://selfhost.directory/project/mobazha): Self-hosted open-source P2P commerce platform where sellers own their storefront and data, connecting to shared marketplaces with multi-chain crypto payments.
- [Monero](https://selfhost.directory/project/monero): Open-source core implementation of the Monero cryptocurrency: run your own self-hosted monerod node and CLI wallet, with pruning, RPC access and Tor support.
- [monero-lws](https://selfhost.directory/project/monero-lws): Self-hosted Monero light-wallet server implementing the MyMonero API with LMDB backend and ZeroMQ block notifications for real-time scanning.
- [monero-nodeboard](https://selfhost.directory/project/monero-nodeboard): Self-hosted Docker project bundling a Monero node and web dashboard for running a remote node with browser UI on your own server.
- [Monero P2Pool](https://selfhost.directory/project/p2pool): Monero P2Pool is a self-hosted, decentralized mining pool using a separate blockchain for zero-fee PPLNS payouts. Requires a Monero node and optionally XMRig miner.
- [NMController_web](https://selfhost.directory/project/nmcontrollerweb): Self-hosted web dashboard that monitors NMMiner and NMAxe devices via UDP broadcast, showing real-time hashrate, temperature, RSSI, and Bitcoin mining statistics.

## Links

- [Homepage](https://gitlab.com/invincible-privacy/joinstr)
- [Website](https://joinstr.xyz)
- [Documentation](https://docs.joinstr.xyz)
- [Community forum](https://forum.joinstr.xyz)

---
Source: https://selfhost.directory/project/joinstr