Running Your Own Mostro Node

Mostro v0.19.2 — Community Guide · October 2026

1. What is Mostro and Why Should Your Community Run One?

Mostro is a peer-to-peer Bitcoin exchange that lets people buy and sell Bitcoin using local currencies (dollars, euros, pesos — any currency) without needing to provide identity documents (KYC). Think of it as a decentralized marketplace where buyers and sellers can trade directly.

It works using two technologies:

• Lightning Network — a fast, low-cost Bitcoin payment layer (think of it as Bitcoin's express lane for small, quick payments)
• Nostr — a censorship-resistant communication protocol (think of it as a messaging system that nobody can shut down)

Mostro acts as an escrow coordinator — it holds the seller's Bitcoin in a temporary "lock box" (called a hold invoice) until the buyer confirms they've sent the local currency payment. Mostro never actually controls anyone's funds; it just holds them briefly during the trade.

Why Would Your Community Want to Run a Mostro Node?

1. Fee income — Every trade earns you a fee (0.6% by default). If your community does $10,000 in monthly trades, that's ~$60/month in fees.
2. P2P trading without KYC — Your community members can buy and sell Bitcoin without providing identity documents. Especially important in regions with unstable currencies or restrictive regulations.
3. Disputes in your language — When a trade goes wrong, your community resolves it, in your language, understanding your local payment methods.
4. Independence — No company can shut down your exchange. No government can pressure a single operator to close it.
5. Customization — You choose which currencies to support, what payment methods to allow, and what fees to charge.

How Mostro Works (Simplified)

If something goes wrong (e.g., Bob says he paid but Alice didn't receive it), either party can open a dispute, and your community's assigned arbiters investigate and resolve it.

2. Prerequisites — What You Need Before Starting

2.1 A Server (VPS)

A VPS (Virtual Private Server) is a computer in a data center that runs 24/7. You'll rent one to host your Mostro node.

Minimum specs:

Estimated monthly cost: $10–$24/month.

Popular VPS providers:

• Hostinger — from ~$7/month (promotional price; renewal may be higher) (KVM 2: 2 vCPU, 8GB RAM, 100GB NVMe, 8TB bandwidth) · Accepts Bitcoin
• Hetzner — €3.49-8/month (CX23 from €3.49, good value, EU-based)
• Digital Ocean — $24/month (4GB RAM, 2 CPUs, 80GB SSD) or $32/month (4GB RAM, 2 Intel CPUs, 120GB NVMe)
• OVH — ~$6-12/month
• Linode/Akamai — $12/month
• Lunanode — Accepts Bitcoin payments

You need to be comfortable connecting to a server via SSH. If you've never done it, search for a tutorial on "Connect to a VPS via SSH" — it's simpler than it sounds.

2.2 A Lightning Network Node (LND)

Lightning Network is a "layer 2" system built on top of Bitcoin that enables fast, cheap payments. To run Mostro, you need an LND node (Lightning Network Daemon) — the specific Lightning software that Mostro works with.

Your options:

What you need from your LND node:

• The tls.cert file (a security certificate)
• A dedicated mostro.macaroon file (an authentication token with only the permissions Mostro needs, see below)
• The gRPC address (typically https://127.0.0.1:10009 if on the same machine)

Generate a dedicated macaroon for Mostro. Do not give Mostro your admin.macaroon: it grants full control over your node and its funds. Bake a macaroon that carries only the permissions Mostro actually uses (read node info, create/settle/cancel hold invoices, send and track payments).

First pick a root key ID that is not already in use. Revoking a macaroon revokes every macaroon sharing its ID, so reusing one would take out unrelated credentials. ID 0 belongs to LND's own macaroons, so choose a free non-zero number and write it down:

lncli listmacaroonids

Then bake the macaroon with the ID you chose (7 in this example — substitute yours):

lncli bakemacaroon --root_key_id 7 \
  --save_to /root/.lnd/data/chain/bitcoin/mainnet/mostro.macaroon \
  info:read invoices:read invoices:write offchain:read offchain:write

This macaroon cannot open or close channels, move on-chain funds, or change your node's configuration. If it ever leaks, revoke it with lncli deletemacaroonid 7 — using the same ID you baked it with — and bake a new one.

2.3 Lightning Liquidity

To facilitate trades, your Lightning node needs channels with Bitcoin in them. Think of Lightning channels as pre-funded payment tunnels. The Bitcoin inside these channels is your "liquidity".

How much do you need?

Start small, grow incrementally. Begin with enough for your community's initial needs and monitor feedback. When traders report orders failing due to insufficient capacity, that's your signal to add more. Listen to your community.

Getting liquidity:

• Open channels to well-connected nodes (use Lightning Network+ or Amboss to find good peers)
• You need outbound capacity (to pay buyers) and inbound capacity (to receive from sellers)
• Getting inbound liquidity is usually harder — consider Lightning Loop, Magma, or channel swap services

2.4 Nostr Keys

Your Mostro node needs its own identity on the Nostr network — a cryptographic key pair with a public key (your node's address) and a private key (your secret).

Generating secure Nostr keys locally with rana:

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install rana - local Nostr key generator
cargo install rana

# Generate a new key pair (with 12-word seed phrase)
rana --generate 12

Rana will generate your private key (nsec), public key (npub), and a backup seed phrase. Keep everything safe! Note: running rana without arguments starts PoW mining (difficulty 10) which can take minutes — use --generate for instant generation. Never generate important keys using online services.

2.5 Technical Skill Level

💡 Our recommendation: If your community has someone comfortable with the Linux command line, they can handle the Docker installation. Native compilation requires system administration experience. Lightning node setup is the most complex part — consider asking someone experienced for help, or using a node-in-a-box solution.

3. Step-by-Step Setup

All installation options share the same first steps. Then choose your preferred option:

• Option A (Docker Hub): Fastest. No compiling, no cloning. Recommended for most.
• Option B (Docker Build): Build the image locally from the repository.
• Option C (Native Build): More control, better for experienced sysadmins.

All assume you already have: ✅ A VPS with Ubuntu · ✅ SSH access · ✅ A working LND node.

Common Steps (for all 3 options)

Step 1: Connect to your VPS

ssh root@YOUR_VPS_IP_ADDRESS

Step 2: Update the system

# Download the latest package information
apt update

# Install all available updates
apt upgrade -y

Step 3: Install Docker and Docker Compose

# Install Docker using the official script
curl -fsSL https://get.docker.com | sh

# Verify Docker is installed
docker --version

# Verify Docker Compose
docker compose version

Step 4: Install additional tools

apt install -y git make

✅ Common steps completed. Now choose your installation option:

Option A: Docker Hub (Fastest — Recommended)

Run Mostro directly from Docker Hub without cloning the repository or compiling. Perfect for VPS deployments.

Step 5: Create configuration directory

mkdir -p ~/mostro-config/lnd

Step 6: Get the configuration template

curl -sL https://raw.githubusercontent.com/MostroP2P/mostro/v0.19.2/settings.tpl.toml \
  -o ~/mostro-config/settings.toml

Step 7: Copy LND credentials

cp /path/to/your/tls.cert ~/mostro-config/lnd/tls.cert
cp /path/to/your/mostro.macaroon ~/mostro-config/lnd/mostro.macaroon

If LND is on the same machine, typical paths are:

• /root/.lnd/tls.cert
• /root/.lnd/data/chain/bitcoin/mainnet/mostro.macaroon

Step 8: Edit the configuration

nano ~/mostro-config/settings.toml

Required changes:

[lightning]
lnd_cert_file = '/config/lnd/tls.cert'
lnd_macaroon_file = '/config/lnd/mostro.macaroon'
lnd_grpc_host = 'https://host.docker.internal:10009'  # If LND on same VPS
# Or use 'https://YOUR_LND_IP:10009' if LND on different server

[database]
url = "sqlite:///config/mostro.db"  # mostrod always uses <config-dir>/mostro.db

[nostr]
nsec_privkey = 'YOUR_NSEC_KEY_HERE'
relays = ['wss://relay.mostro.network', 'wss://nos.lol']

[mostro]
fee = 0.006                    # 0.6% fee per trade
max_order_amount = 1000000     # Maximum order in sats
min_payment_amount = 100       # Minimum order in sats
fiat_currencies_accepted = ['USD', 'EUR']  # Your currencies

Save: Ctrl+X, then Y, then Enter.

Step 9: Fix permissions

sudo chown -R 1000:1000 ~/mostro-config
chmod 700 ~/mostro-config
chmod 600 ~/mostro-config/settings.toml
chmod 600 ~/mostro-config/lnd/mostro.macaroon

Step 10: Run the container

If LND is on the same VPS:

docker run -d --name mostro \
  --restart unless-stopped \
  --add-host=host.docker.internal:host-gateway \
  -v ~/mostro-config:/config \
  mostrop2p/mostro:v0.19.2

If LND is on a different server:

docker run -d --name mostro \
  --restart unless-stopped \
  -v ~/mostro-config:/config \
  mostrop2p/mostro:v0.19.2

Step 11: Check the logs

docker logs -f mostro

Look for these messages:

• Settings correctly loaded! — Configuration is valid
• Transport: nip44 (protocol v2, event kind 14) — Wire protocol in use (see 4.8)
• Connected to 'wss://...' — Nostr relay established
• Recorded Lightning node identity <pubkey> — LND reached (first run only)

🎉 Congratulations! If you see successful connections in the logs, your Mostro node is running!

Alternative: Docker Compose

Instead of a long docker run command you can describe the container in a compose file. It runs the same image with the same settings, and updating becomes a one-line tag change. Create ~/mostro-docker/compose.yml:

mkdir -p ~/mostro-docker
nano ~/mostro-docker/compose.yml

services:
  mostro:
    image: mostrop2p/mostro:v0.19.2
    container_name: mostro
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"  # only if LND runs on this VPS
    volumes:
      - ${HOME}/mostro-config:/config

Start it and follow the logs:

docker compose -f ~/mostro-docker/compose.yml up -d
docker compose -f ~/mostro-docker/compose.yml logs -f mostro

Pick one: docker run or compose, not both. To update either of them, see 5.5.

Option B: Docker Build (Build image locally)

Step 5: Download Mostro

cd /opt
git clone https://github.com/MostroP2P/mostro.git
cd mostro

Step 6: Set up configuration files

cd docker
mkdir -p config
cp ../settings.tpl.toml config/settings.toml

Step 7: Edit the configuration file

nano config/settings.toml

Edit the same settings as Option A, Step 8.

    extra_hosts:
      - "host.docker.internal:host-gateway"

Step 8: Build the Docker image

cd ..
LND_CERT_FILE=/root/.lnd/tls.cert \
LND_MACAROON_FILE=/root/.lnd/data/chain/bitcoin/mainnet/mostro.macaroon \
make docker-build

Step 9: Start Mostro

# Start Mostro and the bundled relay. Plain `make docker-up` also
# starts the StartOS image, which you don't need on a VPS.
docker compose -f docker/compose.yml up -d mostro nostr-relay

# Check status
docker compose -f docker/compose.yml ps

# View logs
docker compose -f docker/compose.yml logs -f mostro

🎉 Congratulations! If you see successful connections, your Mostro node is running!

Option C: Native Build (For Technical Operators)

Step 5: Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source /root/.cargo/env
rustc --version
cargo --version

Step 6: Install build dependencies

apt install -y cmake build-essential libsqlite3-dev libssl-dev \
  pkg-config git sqlite3 protobuf-compiler

Step 7: Download and compile Mostro

cd /opt
git clone https://github.com/MostroP2P/mostro.git
cd mostro
cargo build --release

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

Steps 8–10: Install, initialize, and clean

install target/release/mostrod /usr/local/bin
cargo clean  # Saves 2+ GB of space

Steps 11–12: Create user and configure

adduser --disabled-login mostro
mkdir -p /opt/mostro
cp settings.tpl.toml /opt/mostro/settings.toml
nano /opt/mostro/settings.toml

Edit the same settings as Option A, Step 8.

Steps 13–15: Test, permissions, and systemd service

# Test run
/usr/local/bin/mostrod -d /opt/mostro

# Set permissions
chown -R mostro:mostro /opt/mostro

Create the systemd service:

# /etc/systemd/system/mostro.service
[Unit]
Description=Mostro daemon
After=network.target

[Service]
Type=simple
User=mostro
WorkingDirectory=/home/mostro
Environment=RUST_LOG=info
ExecStart=/usr/local/bin/mostrod -d /opt/mostro
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable mostro.service
systemctl start mostro.service
systemctl status mostro.service

🎉 Congratulations! Your Mostro node is running as a system service.

4. Configuration In Depth

The settings.toml file controls everything about your Mostro node.

4.1 Nostr Keys — Your Node's Identity

[nostr]
nsec_privkey = 'YOUR_NSEC_KEY'
relays = [
  'wss://relay.mostro.network',
  'wss://nos.lol',
  'wss://relay.nostr.band'
]

Which relays to use?

• wss://relay.mostro.network — Mostro's own relay, recommended
• wss://nos.lol — Reliable and well-connected relay
• Add 3–5 relays for reliability. More relays = better availability but more bandwidth.

Keeping the key out of settings.toml

Mostro also reads the key from the MOSTRO_NSEC_PRIVKEY environment variable. Precedence is: environment variable, then <config-dir>/.env, then settings.toml.

# ~/mostro-config/.env  (chmod 600) — loaded automatically at startup
MOSTRO_NSEC_PRIVKEY=nsec1...

# Docker
docker run -e MOSTRO_NSEC_PRIVKEY=nsec1... ...

# systemd unit
Environment="MOSTRO_NSEC_PRIVKEY=nsec1..."

Leaving nsec_privkey in settings.toml still works. If you use the .env file, back it up as carefully as the config itself.

4.2 Fees — How You Earn Revenue

[mostro]
fee = 0.006
dev_fee_percentage = 0.30

Trading fee (fee): Percentage charged per trade, split between buyer and seller.

• 0.006 = 0.6% (each party pays 0.3%)
• 0.01 = 1.0% (each party pays 0.5%)
• 0 = free (good for growing your user base)

Example: On a 100,000 sat trade with fee = 0.006: The buyer pays 300 sats, the seller pays 300 sats, your node earns 600 sats total.

Development fee (dev_fee_percentage): A percentage of your fee earnings that goes to Mostro development.

• 0.30 = 30% (default) — out of 600 sats, 180 go to the development fund
• Minimum: 10% (0.10), Maximum: 100% (1.0)
• Paid by your node from its earnings, not charged to users
• All payments publicly auditable via Nostr events (kind 8383)

4.3 Order Limits and Currencies

[mostro]
max_order_amount = 1000000
min_payment_amount = 100
max_orders_per_response = 10
fiat_currencies_accepted = ['USD', 'EUR', 'ARS', 'CUP']

• max_order_amount: Largest trade in satoshis. Set based on your Lightning channel capacity.
• min_payment_amount: Minimum trade in satoshis. 1,000 or 10,000 is more practical than 100.
• max_orders_per_response: Maximum number of orders Mostro returns in a single query. If a user has more orders than this limit (e.g. when restoring their session from the mobile client), they will receive a cant-do: too_many_requests error and won't be able to recover their orders. If your users trade frequently, increase this value (e.g. 50 or 100). The default of 10 may not be enough.
• fiat_currencies_accepted: Use ISO 4217 codes. Empty array [] accepts all currencies.

4.4 Node Profile (Optional but Recommended)

[mostro]
name = "LatAm Mostro"
about = "P2P Bitcoin exchange for Latin America. Spanish support."
picture = "https://example.com/your-logo.png"
website = "https://your-community-site.com"

These set your Mostro's profile on Nostr (NIP-01 kind 0 metadata). Clients display this information so users know which Mostro they're trading on.

4.5 Timing and Expiration

[mostro]
expiration_hours = 24        # How long an order stays open
expiration_seconds = 900     # Time to complete (15 min)
hold_invoice_expiration_window = 300  # Time a taker has to pay the invoice or add a payout one (5 min)

4.6 Anti-Spam

[mostro]
pow = 0  # 0 = disabled; 10-20 = moderate. Start with 0.

4.7 RPC Admin Interface (Optional)

[rpc]
enabled = false
listen_address = "127.0.0.1"
port = 50051
# auth_token = "a-long-random-string"

This gRPC interface is for operator tooling: grpcurl, and mostro-cli for maintenance mode (admsetmaintenance, admmaintenancestatus, admcancelpending). Mostrix does not use it — it works over Nostr, so you do not need RPC for dispute resolution.

4.8 Wire Protocol (Transport)

A Mostro node speaks one wire protocol, chosen here:

[mostro]
transport = "nip44"

Your node advertises which protocol it speaks in its kind 38385 info event, so capable clients pick the matching format on their own. Mostro Mobile, Mostrix and mostro-cli all support v2.

The v2 transport also allows a sharper anti-spam gate than 4.6. pow applies to every message, while pow_first_contact applies only to senders that are not part of an active trade and is checked before decryption. That keeps ongoing trades cheap while charging strangers real work:

[mostro]
pow = 0                  # ongoing trades
pow_first_contact = 16   # new orders and takes from unknown keys

4.9 Lightning Safety Limits

These [lightning] settings bound how long your channels can stay locked and how many payouts can be unresolved at once. They all have defaults, so a config file from an older version still starts, but a fresh template ships them and they are worth knowing.

[lightning]
max_final_cltv_expiry_delta = 144
escrow_deadline_margin_blocks = 24
max_inflight_payouts = 100
max_inflight_payouts_per_destination = 10
payment_cltv_limit = 1008
allow_node_change = false

Note also that max_routing_fee, in the [mostro] block, now defaults to 0.002 (0.2%).

4.10 Bitcoin Price Sources

Mostro needs a BTC/fiat rate to price orders. With no [price] block it uses a single source, Yadio, through the now-deprecated bitcoin_price_api_url. Adding the block gives you several sources, combined by median with an outlier guard, so one API going down or returning a bad number does not move your prices.

[price]
update_interval_seconds = 300
max_price_staleness_seconds = 1800
outlier_threshold_pct = 5.0        # discard a source this far from the median (needs 3+ sources)
provider_timeout_seconds = 10
provider_failure_threshold = 3     # failures before a source is put on cooldown
provider_failure_cooldown_seconds = 120
publish_to_nostr = true            # publish aggregated rates as kind 30078

[price.providers.yadio]
enabled = true
url = "https://api.yadio.io"

[price.providers.coingecko]
enabled = true
url = "https://api.coingecko.com/api/v3"
# api_key = "CG-xxxx"              # optional, raises rate limits

[price.providers.currency_api]
enabled = true
url = "https://currency-api.pages.dev/v1"
fallback_urls = ["https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1"]
except = ["CUP", "MLC"]            # official rate only, don't mix with informal sources

[price.providers.blockchain]
enabled = true
url = "https://blockchain.info"

Each source takes only or except to scope which currencies it contributes, and fallback_urls for mirrors tried when the main URL fails. An enabled source missing a required secret fails at startup rather than silently producing no quotes.

[price.providers.nostr]
enabled = true
trusted_nodes = [
    # hex pubkeys of Mostro nodes you trust to publish accurate rates
]

Operators serving Cuban pesos can add El Toque for informal-market CUP and MLC. It is opt-in, scoped to those two currencies, and needs a free token — an enabled El Toque without a token refuses to start.

4.11 Other Optional Blocks

Three more blocks you may meet in a fresh template. None is required.

Event retention. How long Mostro keeps each event kind before it expires. Omit the block entirely to accept the defaults.

[expiration]
order_days = 30        # order events (kind 38383)
rating_days = 90       # reputation history (kind 38384)
dispute_days = 90      # disputes, kept longer for auditing (kind 38386)
fee_audit_days = 365   # fee transparency (kind 8383)
dm_days = 30           # protocol-v2 direct messages (kind 14)

Anti-abuse bonds ([anti_abuse_bond]) can require a Lightning hold-invoice bond from takers, makers or both, so abandoning a trade has a cost. Disabled by default and still rolling out in phases. Read the project's docs/ANTI_ABUSE_BOND.md before enabling it on a live node.

Cashu escrow ([cashu]) is an experimental mode that runs without LND and escrows trades in Cashu tokens on a single mint. It is not usable for real trading yet — trade actions are still rejected — and it cannot be combined with anti-abuse bonds. Mentioned here so you know what the block is when you see it.

5. Operating Your Mostro Node

5.1 How Disputes Work

Disputes are your most important operational responsibility.

When do disputes happen?

• The buyer says they paid, the seller says they didn't receive it
• The seller refuses to release Bitcoin after receiving payment
• Either party becomes unresponsive

The dispute process:

1. User opens a dispute — Either party clicks "Dispute" in their client
2. Mostro flags the order — Status changes to "Dispute", funds remain locked
3. Arbiter takes the case — An admin assigned to your node investigates
4. Investigation — Communicates with both parties, requests evidence
5. Resolution — Arbiter decides: release to buyer, or refund to seller

Solver permission levels

A solver can be registered read-only or with full powers. Both levels can take a dispute and talk to the parties, but only a read-write solver can decide where the money goes.

A bare npub1... with no suffix defaults to read-write, and so does registration over the RPC interface. Start a new arbiter on :read while they learn the process, then re-register them read-write once you trust their judgement.

5.2 Mostrix — Your Admin Tool

Mostrix is a terminal-based (TUI) client for dispute resolution. If you run a Mostro node, you need Mostrix.

Option A: Download Pre-built Binary (Recommended)

Download the latest release for your platform from GitHub Releases:

# Linux (x86_64)
wget https://github.com/MostroP2P/mostrix/releases/latest/download/mostrix-x86_64-unknown-linux-musl

# Linux (ARM64 / Raspberry Pi 4)
wget https://github.com/MostroP2P/mostrix/releases/latest/download/mostrix-aarch64-unknown-linux-musl

# Windows
# Download mostrix-x86_64-pc-windows-gnu.exe from the releases page

Verify the download before running it, as described just below.

curl https://raw.githubusercontent.com/MostroP2P/mostrix/main/keys/negrunch.asc | gpg --import
curl https://raw.githubusercontent.com/MostroP2P/mostrix/main/keys/arkanoider.asc | gpg --import

wget https://github.com/MostroP2P/mostrix/releases/latest/download/manifest.txt
wget https://github.com/MostroP2P/mostrix/releases/latest/download/manifest.txt.sig.arkanoider

# Verify each signature you downloaded
gpg --verify manifest.txt.sig.arkanoider manifest.txt

# Then check the binary's hash against the manifest
shasum -a 256 mostrix-x86_64-unknown-linux-musl
grep mostrix-x86_64-unknown-linux-musl manifest.txt

Only once a signature and the hash check out, make the binary executable and start it:

chmod +x mostrix-x86_64-unknown-linux-musl
./mostrix-x86_64-unknown-linux-musl

Option B: Build from Source

If you prefer to compile from source or need a platform not in the releases:

# Install dependencies (Ubuntu/Debian)
sudo apt install -y cmake build-essential pkg-config

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/MostroP2P/mostrix.git
cd mostrix
cargo build --release

# Run
./target/release/mostrix

First Run & Configuration

On first run, Mostrix automatically generates a ~/.mostrix/settings.toml with sensible defaults including a fresh Nostr keypair. Your generated npub will be printed to the terminal.

# Edit the config
nano ~/.mostrix/settings.toml

# Change this line to YOUR Mostro node's pubkey:
mostro_pubkey = "YOUR_MOSTRO_PUBKEY_HEX"

For admin mode (dispute resolution), also configure:

# ~/.mostrix/settings.toml
mostro_pubkey = "YOUR_MOSTRO_PUBKEY_HEX"
nsec_privkey = "nsec1your_personal_key"      # Auto-generated on first run
admin_privkey = "nsec1your_admin_key"        # The daemon's own nsec — see below
relays = ["wss://relay.mostro.network"]
currencies_filter = []                        # Empty = show all currencies
user_mode = "admin"                           # Enable admin mode

ADMIN_NSEC=nsec1... mostro-cli admaddsolver -n npub1solver...

5.3 mostro-watchdog — Dispute Notifications on Telegram

mostro-watchdog monitors your Mostro node for disputes and sends instant alerts via Telegram. Essential for fast response times.

Option A: Automatic Installation (Recommended)

# Download and run the installation script
curl -fsSL https://raw.githubusercontent.com/MostroP2P/mostro-watchdog/main/install.sh | bash

Option B: Manual Binary Download

# Linux x86_64 (Intel/AMD)
curl -LO https://github.com/MostroP2P/mostro-watchdog/releases/latest/download/mostro-watchdog-linux-x86_64
chmod +x mostro-watchdog-linux-x86_64
sudo mv mostro-watchdog-linux-x86_64 /usr/local/bin/mostro-watchdog

# Linux ARM64 (Raspberry Pi, ARM servers)
curl -LO https://github.com/MostroP2P/mostro-watchdog/releases/latest/download/mostro-watchdog-linux-aarch64
chmod +x mostro-watchdog-linux-aarch64
sudo mv mostro-watchdog-linux-aarch64 /usr/local/bin/mostro-watchdog

Option C: Build from Source

git clone https://github.com/MostroP2P/mostro-watchdog.git
cd mostro-watchdog
cargo build --release
sudo cp target/release/mostro-watchdog /usr/local/bin/

Configuration:

cp config.example.toml config.toml
nano config.toml

[mostro]
pubkey = "YOUR_MOSTRO_PUBKEY"

[nostr]
relays = ["wss://relay.mostro.network", "wss://nos.lol"]

[telegram]
bot_token = "YOUR_BOT_TOKEN"
chat_id = -1001234567890

5.4 Uptime Monitoring

Your node needs to be running 24/7.

# Native
systemctl status mostro.service
journalctl -u mostro -f
journalctl -u mostro | grep -E "(error|warn|connected)" --ignore-case

# Docker Hub (Option A)
docker ps --filter name=mostro
docker logs -f mostro

# Docker Build (Option B)
docker compose -f /opt/mostro/docker/compose.yml ps
docker compose -f /opt/mostro/docker/compose.yml logs -f mostro

Checking your node from the outside

Your node republishes an info event (kind 38385) describing itself: fees, currencies, protocol version, maintenance flag. Reading it from a relay is the quickest way to confirm the outside world sees what you think it does.

cargo install nostreq nostcat
nostreq --kinds 38385 --limit 1 --authors YOUR_MOSTRO_PUBKEY_HEX \
  | nostcat --stream wss://relay.mostro.network | jq

5.5 Updating Mostro

Updating replaces the mostrod binary and nothing else: settings.toml and mostro.db stay where they are. Database migrations run on their own when the new version starts, so there is no extra step.

Before you update

1. Read the release notes of the version you are moving to. Your settings.toml is never overwritten, so a new option only takes effect once you add it: compare your file with the new settings.tpl.toml.
2. Back up the database with the commands in 5.6. You need that backup to roll back.

Docker Hub (docker run)

export MOSTRO_TAG=v0.19.2
# Pull first: the running node stays up during the download
docker pull mostrop2p/mostro:$MOSTRO_TAG
docker stop mostro
docker rm mostro
docker run -d --name mostro \
  --restart unless-stopped \
  --add-host=host.docker.internal:host-gateway \
  -v ~/mostro-config:/config \
  mostrop2p/mostro:$MOSTRO_TAG

Use the same flags you installed with (drop --add-host if LND is on another server). If you don't remember them, check docker inspect mostro before removing the container.

Docker Hub (Docker Compose)

export MOSTRO_TAG=v0.19.2
COMPOSE=~/mostro-docker/compose.yml
# Point the image line at the new tag, and check it
sed -i "s|image: mostrop2p/mostro:.*|image: mostrop2p/mostro:$MOSTRO_TAG|" $COMPOSE
grep image: $COMPOSE
docker compose -f $COMPOSE pull
# Recreates the container because the image changed
docker compose -f $COMPOSE up -d

Docker Build

cd /opt/mostro
git fetch --tags
git checkout v0.19.2
make docker-build
make docker-down
make docker-up

Native

cd /opt/mostro
git fetch --tags
git checkout v0.19.2
cargo build --release
install target/release/mostrod /usr/local/bin
cargo clean
systemctl restart mostro.service

Check the new version

# Docker Hub (docker run)
docker exec mostro mostrod --version
docker logs -f mostro

# Docker Hub (Docker Compose)
docker compose -f ~/mostro-docker/compose.yml exec mostro mostrod --version
docker compose -f ~/mostro-docker/compose.yml logs -f mostro

# Docker Build
docker compose -f /opt/mostro/docker/compose.yml exec mostro mostrod --version
docker compose -f /opt/mostro/docker/compose.yml logs -f mostro

# Native
mostrod --version
journalctl -u mostro -f

Look for the same startup messages as on the first run (Step 11 of Option A).

Rolling back

If the new version misbehaves, go back to the previous tag. The new version may already have migrated the database, and an older mostrod can refuse to start with it, so restore the backup you took before updating:

docker stop mostro
docker rm mostro
# replace YYYYMMDD with the date of the backup taken before updating
BACKUP=/root/mostro-backups/mostro.db.YYYYMMDD
cp "$BACKUP" ~/mostro-config/mostro.db
rm -f ~/mostro-config/mostro.db-wal ~/mostro-config/mostro.db-shm
chown 1000:1000 ~/mostro-config/mostro.db
# then start the previous tag: same docker run command,
# or put the old tag back in compose.yml and run docker compose up -d

Docker Build and native work the same way: check out the previous tag, rebuild, and restore the database before starting.

5.6 Backups

Critical files to back up: settings.toml, the .env file if you keep your nsec there (see 4.1), and mostro.db (order history, reputation).

# Manual backup — Docker Hub:
mkdir -p /root/mostro-backups
sqlite3 ~/mostro-config/mostro.db ".backup '/root/mostro-backups/mostro.db.$(date +%Y%m%d)'"
cp ~/mostro-config/settings.toml /root/mostro-backups/settings.toml.$(date +%Y%m%d)
cp ~/mostro-config/.env /root/mostro-backups/env.$(date +%Y%m%d) 2>/dev/null

# Manual backup — Docker Build (Option B):
sqlite3 /opt/mostro/docker/config/mostro.db ".backup '/root/mostro-backups/mostro.db.$(date +%Y%m%d)'"
cp /opt/mostro/docker/config/settings.toml /root/mostro-backups/settings.toml.$(date +%Y%m%d)

# Manual backup — Native:
sqlite3 /opt/mostro/mostro.db ".backup '/root/mostro-backups/mostro.db.$(date +%Y%m%d)'"
cp /opt/mostro/settings.toml /root/mostro-backups/settings.toml.$(date +%Y%m%d)

Automated daily backup (add to crontab with crontab -e):

# Docker Hub (Option A):
0 3 * * * mkdir -p /root/mostro-backups && sqlite3 /root/mostro-config/mostro.db ".backup '/root/mostro-backups/mostro.db.$(date +\%Y\%m\%d)'" && cp /root/mostro-config/settings.toml /root/mostro-backups/settings.toml.$(date +\%Y\%m\%d)

# Docker Build (Option B):
0 3 * * * mkdir -p /root/mostro-backups && sqlite3 /opt/mostro/docker/config/mostro.db ".backup '/root/mostro-backups/mostro.db.$(date +\%Y\%m\%d)'" && cp /opt/mostro/docker/config/settings.toml /root/mostro-backups/settings.toml.$(date +\%Y\%m\%d)

# Native (Option C):
0 3 * * * mkdir -p /root/mostro-backups && sqlite3 /opt/mostro/mostro.db ".backup '/root/mostro-backups/mostro.db.$(date +\%Y\%m\%d)'" && cp /opt/mostro/settings.toml /root/mostro-backups/settings.toml.$(date +\%Y\%m\%d)

5.7 Reviewing Trade Activity

# Count all orders
sqlite3 /path/to/mostro.db "SELECT COUNT(*) FROM orders;"

# Recent successful trades
sqlite3 /path/to/mostro.db "SELECT id, fiat_code, fiat_amount, amount, fee, status, created_at FROM orders WHERE status = 'success' ORDER BY created_at DESC LIMIT 10;"

# Pending orders
sqlite3 /path/to/mostro.db "SELECT id, fiat_code, fiat_amount, status, created_at FROM orders WHERE status = 'pending';"

# Fee revenue: orders.fee stores each party's half, so the node's gross fee is fee*2 and the dev fee is deducted from it
sqlite3 /path/to/mostro.db "SELECT SUM(fee*2) AS gross_fees, SUM(dev_fee) AS dev_fees, SUM(fee*2 - COALESCE(dev_fee, 0)) AS net_fees FROM orders WHERE status = 'success';"

5.8 Maintenance Mode and Changing Your Lightning Node

Hold invoices, bonds and in-flight payouts belong to the Lightning node that created them. Pointing Mostro at a different node while any of that is open would strand those trades, so the daemon refuses to start when it sees a new LND identity with escrow still bound to the old one:

REFUSING TO START: Lightning node changed from ... but escrow is still bound to the old node

Maintenance mode is how you drain first. While it is on, new orders and takes are rejected and open trades keep working, so escrow can settle. It needs the RPC interface enabled (see 4.7).

1. Announce the window to your users well ahead of time.
2. Turn maintenance mode on: mostro-cli admsetmaintenance -e true -r "LN node migration".
3. Poll mostro-cli admmaintenancestatus until it reports drained = true. Pending orders expire on their own; to shorten the drain you can cancel one with mostro-cli admcancelpending -o <order-id>, which releases the maker's bond immediately. Announce that first, it is the user's order. Close long-running disputes as usual.
4. Keep the old node online the whole time. It still has to finish in-flight payouts.
5. Stop Mostro and back up mostro.db.
6. Point [lightning] at the new node and leave allow_node_change = false.
7. Start Mostro. It records the new pubkey. Turn maintenance mode off and place a test order.
8. Only now decommission the old node.

5.9 Operator Commands with mostro-cli

Mostrix is the comfortable way to work disputes, but mostro-cli covers the same ground from a shell and has a few commands Mostrix does not. Dispute commands are signed with a Nostr key you pass as ADMIN_NSEC, which must be the daemon's own key or a registered solver's.

# Dispute work (over Nostr, needs ADMIN_NSEC)
export ADMIN_NSEC=nsec1...
mostro-cli listdisputes
mostro-cli admtakedispute -d <dispute-id>
mostro-cli admsenddm -p <npub> -m "message to a party"
mostro-cli admsettle -o <order-id>      # release to the buyer
mostro-cli admcancel -o <order-id>      # refund the seller

# Register an arbiter, optionally read-only
mostro-cli admaddsolver -n npub1...:read

A separate group of commands goes over the admin gRPC instead of Nostr, so they need MOSTRO_RPC_URL and MOSTRO_RPC_TOKEN rather than ADMIN_NSEC, and the RPC interface enabled (see 4.7).

export MOSTRO_RPC_URL=http://127.0.0.1:50051
export MOSTRO_RPC_TOKEN=your-auth-token

mostro-cli admsetmaintenance -e true -r "reason"
mostro-cli admmaintenancestatus
mostro-cli admcancelpending -o <order-id>

admcancelpending is worth knowing outside a migration. It cancels an order that is still pending or waiting for a taker's bond, notifies the maker and releases every bond on it at once. Use it for an order that is clearly abandoned or mispriced, and tell the maker first — it is their order, and this is not a dispute resolution.

6. Cost Breakdown

Monthly Operating Costs

One-time / Capital Costs

Revenue Potential

Time Commitment

7. Frequently Asked Questions

Do I need to be a developer to run a Mostro node?

No, but you need to be comfortable with basic command line operations (typing commands, editing text files). The Docker path (Option A) is designed to be accessible.

Can I run Mostro on a Raspberry Pi?

Technically yes (using Start9 or similar), but not recommended for production due to CPU and RAM limitations. A VPS is more reliable.

Can I use Core Lightning (CLN) instead of LND?

No. Mostro currently only supports LND because it depends on LND's specific hold invoice implementation. Support for other implementations may come in the future.

How do users connect to my Mostro?

Users need a Mostro client app (like Mostro Mobile or mostro-cli) and your Mostro's public key (npub). They add your npub to their client, and the client communicates through Nostr relays. No direct connection needed.

Can I run multiple Mostro instances?

Yes, but each one needs its own Nostr key pair, LND node (or at least separate channels/liquidity), and configuration.

Is it legal?

It depends heavily on your jurisdiction. Mostro is software for peer-to-peer trading. In some jurisdictions, operating a P2P exchange may require licenses. Check local regulations and seek legal advice.

How much bandwidth does Mostro use?

Very little — mostly small Nostr events. A few GB per month is typical even with moderate volume.

What happens if my node goes offline?

Pending orders eventually expire. Active trades with locked funds continue when you come back online. If you're offline too long, users may lose trust. Since v0.18.3 there is also an escrow deadline: if you stay down long enough for the hold invoice to approach its CLTV horizon, LND cancels it and the seller is refunded automatically.

Can I change my Nostr key later?

You can, but you'll lose your node's identity and reputation. Users will see it as a new Mostro. Treat your key as your brand identity.

Can I lose money running a Mostro node?

Yes, it's possible: Lightning channel funds could be at risk from bugs (rare); forced channel closures during high fee periods can be costly; VPS costs are ongoing.

Is Lightning liquidity "at risk"?

Your Lightning liquidity is yours. It's not at risk from Mostro itself — hold invoices are temporary locks. However, standard Lightning Network risks apply (forced closures, stuck channels, bugs).

When will I break even?

It depends on your costs and trading volume. With $20/month in costs and 0.6% fee, you need ~$5,000/month in trades to cover costs (before the development fee). Most communities take 3–6 months to build significant volume.

Can I move Mostro to a different Lightning node?

Yes, but not by editing the config and restarting. Escrow is bound to the node that created it, so you drain it in maintenance mode first and the daemon refuses to start if you skip that. Moving the same node to a new host is not a node change and needs nothing special. See 5.8.

8. Security Considerations

Keep Your Node's Key Out of Reach

Your nsec_privkey is your node's identity, and anyone holding it can impersonate your Mostro. Prefer supplying it through the MOSTRO_NSEC_PRIVKEY environment variable or a chmod 600 .env file over leaving it in settings.toml (see 4.1). Never put it on a laptop for dispute work either: register a separate solver key for that (see 5.2).

Operating Under Authoritarian Regimes

If you operate in a country with an authoritarian government, privacy is not optional — it's a security requirement.

1. Run your Mostro node behind Tor and/or a VPN. This hides your server's IP from Nostr relays.
2. If Tor/VPN is not possible (common in developing countries with slow internet), only publish events to relays you own or trust.
3. Be very careful about which relays you use. In the future, governments could create Nostr relays specifically to collect IP addresses.
4. Consider your Lightning node's privacy as well. Running LND behind Tor is possible and recommended in sensitive environments.

9. Troubleshooting

Mostro won't start

dev_fee_percentage (0.05) is below minimum (0.1)

Set dev_fee_percentage to at least 0.10 in settings.toml.

Configuration file or database not found

Make sure the -d flag points to the directory containing settings.toml. For Docker Hub: verify that ~/mostro-config/settings.toml exists.

Mostro exits at startup with Ln node error

• Verify LND is running: lncli getinfo
• Check that lnd_grpc_host matches your LND address
• Verify tls.cert and mostro.macaroon paths are correct
• Verify the macaroon carries the permissions from 2.2
• Docker + LND on the host: use host.docker.internal. Option B also needs the extra_hosts mapping.

REFUSING TO START: Lightning node changed

Mostro is pointed at a different LND identity while escrow is still open on the old one. Reconnect the old node and drain it before switching. See 5.8.

Clients don't see my orders, or can't message my node

Check the Transport: line in your logs. A node on nip44 is invisible to protocol-v1-only clients, and a node on gift-wrap is invisible to v2 clients. See 4.8.

Payouts fail with "no route"

Check payment_cltv_limit. It must sit at least 576 blocks above max_final_cltv_expiry_delta, and must not exceed your LND's --max-cltv-expiry. See 4.9.

Connection problems

Mostro starts but doesn't connect to relays

• Check relay URLs (must start with wss://)
• Make sure your VPS firewall allows outbound connections on port 443
• Try different relays — some may be temporarily down

Trade problems

A user gets "cant-do: too_many_requests" when restoring session

This happens when the user has more orders (historical + active) than the max_orders_per_response value in your configuration. The client tries to query all their orders at once and Mostro rejects it. This is not a ban or a temporary block — it will keep happening until you adjust the value.

# In settings.toml, increase the limit:
max_orders_per_response = 50  # default is 10, maximum 255

The value is stored as a single byte, so 255 is the ceiling. If a user has more orders than that, they need to prune their history rather than you raising the limit further.

Orders don't appear in clients

• Check relay connections in the logs
• Make sure clients use the same relays as your node

Payments failing

• Check liquidity: lncli listchannels
• Make sure you have enough outbound capacity
• Check the max_routing_fee setting

Database problems

Database locked errors

ps aux | grep mostrod
# If multiple processes, kill the extras:
kill <PID>

Getting help

1. Check the logs first — most errors explain what went wrong
2. Telegram (Developers): @mostro_dev
3. Telegram (Community): @MostroP2P
4. GitHub Issues: github.com/MostroP2P/mostro/issues
5. DeepWiki: deepwiki.com/MostroP2P/mostro

When asking for help, always include: your Mostro version, relevant log output, and what you've already tried.

Appendix: Quick Reference

Important File Locations

Essential Commands

# Docker
docker logs -f mostro         # View logs
docker restart mostro          # Restart
docker stop mostro             # Stop

# Native (systemd)
systemctl start mostro         # Start
systemctl stop mostro          # Stop
systemctl restart mostro       # Restart
systemctl status mostro        # View status
journalctl -u mostro -f        # View logs

# Database
sqlite3 mostro.db "SELECT COUNT(*) FROM orders;"                           # Total orders
sqlite3 mostro.db "SELECT COUNT(*) FROM orders WHERE status='success';"    # Successful trades
sqlite3 mostro.db "SELECT SUM(fee*2 - COALESCE(dev_fee, 0)) FROM orders WHERE status='success';"  # Net fees kept by the node

Recommended Configuration for New Nodes

[mostro]
fee = 0.006
max_order_amount = 500000
min_payment_amount = 1000
expiration_hours = 24
expiration_seconds = 900
pow = 0
dev_fee_percentage = 0.30
fiat_currencies_accepted = ['USD']  # Change to your local currency

[nostr]
relays = [
  'wss://relay.mostro.network',
  'wss://nos.lol',
  'wss://relay.nostr.band'
]