Prerequisites

Software:

Optional (for Meshtastic CLI testing):

Hardware (see Hardware for details):

CLI Compile & Run

Quick Install

  1. Install system dependencies:

    # Debian/Ubuntu/Raspberry Pi OS
sudo apt-get install build-essential pkg-config libglib2.0-dev \
  libssl-dev libjson-glib-dev libmicrohttpd-dev protobuf-compiler xxd

    Verify they're all found:

    pkg-config --modversion glib-2.0 openssl json-glib-1.0
# Should print three version numbers — if any fail, the build will fail

  2. Set up Python environment for protobuf generation:

    The nanopb generator that compiles Meshtastic protobufs requires specific Python packages. Use a venv to avoid conflicts with system Python:

    python3 -m venv venv
source venv/bin/activate
pip install protobuf grpcio-tools

    Keep this venv active for the build step. You can deactivate it after make completes.

  3. Clone and build:

    git clone https://github.com/gnarzilla/deadmesh.git
cd deadmesh
make clean && make UI=1
deactivate  # exit venv after build

    A successful build produces:

    bin/deadmesh
bin/plugins/adblocker.so
bin/plugins/meshtastic.so
bin/plugins/ratelimiter.so
tools/mesh-sim

  4. Connect your Meshtastic radio:

    # Most devices appear as /dev/ttyACM0 or /dev/ttyUSB0
ls -l /dev/ttyACM0 /dev/ttyUSB0 2>/dev/null

# Add yourself to the dialout group
sudo usermod -a -G dialout $USER
# Log out and back in for group change to take effect

  5. Generate CA certificate (for HTTPS interception):

    Create the cert directory first, then generate a local CA:

    mkdir -p ~/.deadlight

openssl genrsa -out ~/.deadlight/ca.key 4096
openssl req -new -x509 -days 3650 \
  -key ~/.deadlight/ca.key \
  -out ~/.deadlight/ca.crt \
  -subj "/CN=deadmesh CA/O=deadlight/C=US"

chmod 600 ~/.deadlight/ca.key
chmod 644 ~/.deadlight/ca.crt

    Install it system-wide so curl and other tools trust it:

    sudo cp ~/.deadlight/ca.crt /usr/local/share/ca-certificates/deadmesh.crt
sudo update-ca-certificates

    Copying from another machine? If you already have a CA from a previous install (e.g. WSL), copy both ca.crt and ca.key to ~/.deadlight/ on the new machine instead of generating new ones.

  6. Configure — create deadmesh.conf:

    [core]
port = 8080
max_connections = 50
log_level = info

[meshtastic]
enabled = true
serial_port = /dev/ttyACM0
baud_rate = 115200
mesh_node_id = 0          ; 0 = auto-detect from device
fragment_size = 220
ack_timeout = 30000
max_retries = 3
hop_limit = 3

[ssl]
enabled = true
ca_cert_file = /home/youruser/.deadlight/ca.crt
ca_key_file = /home/youruser/.deadlight/ca.key

[network]
connection_pool_size = 5
connection_pool_timeout = 600
upstream_timeout = 120

    Important: Use absolute paths for ca_cert_file and ca_key_file — replace youruser with your actual username. The ~ shortcut expands to /root/ when running with sudo, which is not where your certs are.

  7. Run the gateway:

    ./bin/deadmesh -c deadmesh.conf -v

    You should see:

    • Configuration loaded and Config applied — config is valid
    • Meshtastic: sent want_config handshake — serial API initialized
    • Meshtastic: auto-detected local node ID: XXXXXXXX — device recognized
    • Meshtastic: NodeInfo update for XXXXXXXX — mesh nodes populating
    • Live packet stream: POSITION, TELEMETRY, TEXT, NODEINFO from mesh

    If you see Configuration validation failed: Cannot read CA cert file — the path in your config doesn't match where you put the certs. Double-check the absolute path and that ~/.deadlight/ca.crt exists.

  8. Open the dashboard at http://localhost:8081 to monitor gateway activity.

  9. Test the proxy:

    # HTTP
curl -x http://localhost:8080 http://example.com

# HTTPS
curl --cacert ~/.deadlight/ca.crt -x http://localhost:8080 https://example.com

# SOCKS5
curl --socks5 localhost:8080 http://example.com

Client-side Proxy (send device/second radio)

The deadmesh-client binary runs a tiny local HTTP proxy that tunnels traffic over the mesh to your gateway.

Build note: Serial mode requires a compile-time flag

# Add -DCLIENT_TRANSPORT_SERIAL to client target in Makefile (see earlier instructions)
make clean client UI=1

Run on client device (replace with your gateway's node ID):

./bin/deadmesh-client --gateway 14e7cdaf --device /dev/ttyACM0 -v
# or Bluetooth serial
./bin/deadmesh-client --gateway 14e7cdaf --device /dev/rfcomm0 -v

Once running (listens on localhost:8888):

export http_proxy=http://localhost:8888
curl http://example.com
Windows Subsystem for Linux ### WSL (Windows Subsystem for Linux)

deadmesh works under WSL2 with USB/IP passthrough for the Meshtastic radio. This is a fully supported configuration — the reference gateway setup during development runs this way.

# PowerShell (Admin) — install and attach USB device
winget install usbipd
usbipd list                              # Find your radio's BUSID
usbipd bind --busid <BUSID>             # One-time bind
usbipd attach --wsl --busid <BUSID>     # Attach to WSL (repeat after replug)
# WSL — verify device
ls -l /dev/ttyACM0
sudo usermod -a -G dialout $USER

Note: You must re-run usbipd attach from PowerShell each time the radio is unplugged, the PC sleeps, or WSL restarts.