{"id":45163300,"url":"https://github.com/gnarzilla/meshtastic.deadlight","last_synced_at":"2026-02-20T06:05:40.777Z","repository":{"id":324322612,"uuid":"1096799898","full_name":"gnarzilla/meshtastic.deadlight","owner":"gnarzilla","description":"Internet-over-LoRa: A practical bridge between Meshtastic mesh networks and the Internet","archived":false,"fork":false,"pushed_at":"2026-02-17T06:52:12.000Z","size":115473,"stargazers_count":10,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-17T12:13:28.398Z","etag":null,"topics":["lora-gateway","meshtastic","meshtastic-udp","tun","vpn-gateway"],"latest_commit_sha":null,"homepage":"https://meshtastic.deadlight.boo","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gnarzilla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T01:07:27.000Z","updated_at":"2026-02-17T06:52:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gnarzilla/meshtastic.deadlight","commit_stats":null,"previous_names":["gnarzilla/meshtastic.deadlight"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gnarzilla/meshtastic.deadlight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnarzilla%2Fmeshtastic.deadlight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnarzilla%2Fmeshtastic.deadlight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnarzilla%2Fmeshtastic.deadlight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnarzilla%2Fmeshtastic.deadlight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gnarzilla","download_url":"https://codeload.github.com/gnarzilla/meshtastic.deadlight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnarzilla%2Fmeshtastic.deadlight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29642914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T05:21:04.652Z","status":"ssl_error","status_checked_at":"2026-02-20T05:21:04.238Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lora-gateway","meshtastic","meshtastic-udp","tun","vpn-gateway"],"created_at":"2026-02-20T06:05:40.286Z","updated_at":"2026-02-20T06:05:40.772Z","avatar_url":"https://github.com/gnarzilla.png","language":"C","funding_links":["https://ko-fi.com/gnarzilla"],"categories":[],"sub_categories":[],"readme":"# Deadlight Meshtastic Proxy\n\n**Internet-over-LoRa: A practical bridge between Meshtastic mesh networks and the Internet**\n\n[![Meshtastic](https://meshtastic.deadlight.boo/favicon.ico)](https://meshtastic.deadlight.boo) [Project/Community Blog](https://meshtastic.deadlight.boo) · [Why This Exists](#why-this-exists) · [Getting Started](#getting-started) · [Hardware](#hardware) · [Usage](#usage) · [Configuration](#configuration) · [How It Works](#how-it-works) · [Real-World Use Cases](#real-world-use-cases) · [Performance](#performance) · [Roadmap](#roadmap) · [License](#license)\n\n![Deadlight-Mesh Web UI](src/assets/Deadlight-Mesh-webUI.gif)\n\n## Overview\n\nDeadlight Meshtastic Proxy transforms LoRa mesh networks into practical Internet gateways. Built on the [Deadlight Proxy](https://github.com/gnarzilla/proxy.deadlight) foundation, it adds transparent mesh networking capabilities that let any device on a Meshtastic mesh access standard Internet protocols including HTTP/HTTPS, email, DNS, FTP, as if they had normal connectivity.\n\n**What makes this different from other mesh solutions:**\n- Standard protocols work unchanged (browse websites, send email, use apps)\n- Transparent to applications (no special client software needed)\n- Automatic fragmentation and reassembly for mesh transport\n- Full MITM proxy capabilities for traffic inspection/modification\n- Works with existing Meshtastic hardware and networks\n- Truly off-grid: solar-powered nodes can provide connectivity across kilometers\n\nThink of it as giving your Meshtastic network the capabilities of a satellite terminal, but running on $30 hardware and zero monthly fees.\n\n![Deadlight Meshtastic Proxy (no lora)](src/assets/output.gif)\n\n## Why This Exists\n\nMeshtastic networks are incredible for messaging and telemetry, but they weren't designed for general Internet access. Each protocol (HTTP, SMTP, DNS) would need custom mesh-aware implementations. This creates a chicken-and-egg problem: applications won't add mesh support without users, users won't adopt mesh without applications.\n\nDeadlight solves this by sitting in the middle:\n1. Mesh side: Speaks fluent Meshtastic (protobuf over LoRa serial)\n2. Internet side: Speaks every protocol your applications already use\n3. Bridges transparently: Fragments outgoing requests, reassembles incoming responses\n\n**Result**: Your mesh network suddenly works with everything, email clients, web browsers, update tools, API services, all without modifying a single line of application code.\n\n### Critical Scenarios This Enables\n\n- **Disaster Response**: Coordinate rescue operations when cell towers are down\n- **Rural Connectivity**: Share one satellite uplink across dozens of kilometers\n- **Censorship Resistance**: Maintain communication during Internet blackouts\n- **Off-Grid Networks**: Festival/protest/research networks that disappear when powered off\n- **Development Projects**: Bring Internet services to areas with zero infrastructure\n\n## Features\n\n- **Universal Protocol Support**: HTTP/HTTPS, SMTP/IMAP, SOCKS5, WebSocket, FTP, DNS—if it runs over TCP/IP, it works\n- **Transparent TLS Interception**: Inspect and cache HTTPS traffic to minimize mesh bandwidth\n- **Intelligent Fragmentation**: Automatically chunks large requests/responses into ~220-byte Meshtastic packets\n- **Store-and-Forward**: Delay-tolerant networking handles intermittent mesh connectivity\n- **Connection Pooling**: Reuses upstream connections to reduce mesh overhead\n- **Plugin Extensibility**: Add custom filters, caching, compression, or protocol handlers\n- **Hardware Flexibility**: Works with USB serial, Bluetooth, or TCP-connected radios\n- **Zero-Config Detection**: Auto-discovers Meshtastic devices on serial ports\n\n## Getting Started\n\n### Prerequisites\n\n**Software**:\n- Linux system (Raspberry Pi, x86 server, or ESP32-S3 with adequate RAM)\n- GLib 2.0+, OpenSSL 1.1+\n- GCC or Clang\n\n**Hardware** (see [Hardware](#hardware) section for details):\n- Meshtastic-compatible LoRa radio (ESP32-based recommended)\n- Gateway node: Raspberry Pi or similar with Internet connection\n- Client nodes: Any Meshtastic device (phone, handheld, custom)\n\n### Quick Install\n\n1. **Clone and build**:\n   ```bash\n   git clone https://github.com/gnarzilla/meshtastic.deadlight.git\n   cd meshtastic.deadlight\n   make clean \u0026\u0026 make UI=1\n   ```\n\n2. **Install CA certificate** (for HTTPS interception):\n   ```bash\n   # The proxy generates these on first run:\n   # /etc/deadlight/ca.crt (install on clients)\n   # /etc/deadlight/ca.key (keep secret)\n   \n   # Debian/Ubuntu\n   sudo cp /etc/deadlight/ca/ca.crt /usr/local/share/ca-certificates/deadlight-mesh.crt\n   sudo update-ca-certificates\n   ```\n\n3. **Connect your Meshtastic radio**:\n   ```bash\n   # Most devices appear as /dev/ttyACM0 or /dev/ttyUSB0\n   ls -l /dev/tty*\n   \n   # Give yourself permission (or run as root)\n   sudo usermod -a -G dialout $USER\n   ```\n\n4. **Run the proxy**:\n   ```bash\n   sudo ./bin/deadlight -c meshtastic.conf\n   ```\n\n5. **Configure mesh clients** to use the gateway's mesh address as their proxy (see [Usage](#usage)).\n\n## Hardware\n\n### Recommended Gateway Setup\n\n**Option 1: Raspberry Pi Gateway** (most versatile)\n- Raspberry Pi 4/5 (2GB+ RAM)\n- RAK WisBlock Meshtastic Starter Kit or Heltec LoRa 32 V3\n- Connection: USB serial or GPIO UART\n- Power: 5V/3A supply or 12V solar panel + battery\n\n**Option 2: ESP32-S3 All-in-One** (compact)\n- Lilygo T-Deck or T-Watch S3\n- 8MB+ PSRAM required for Deadlight\n- Built-in LoRa radio and display\n- Power: LiPo battery + solar panel\n\n**Option 3: Industrial/Outdoor**\n- Heltec Wireless Tracker or Mesh Node T114\n- Weatherproof enclosure\n- High-gain directional antenna (5-8 dBi)\n- Solar panel + LiFePO4 battery for 24/7 operation\n\n### Client Devices\n\nAny Meshtastic-compatible device works:\n- **Android/iOS**: Meshtastic app on phone (Bluetooth to radio)\n- **Handheld**: RAK WisBlock, Lilygo T-Echo, Heltec LoRa 32\n- **Custom**: ESP32 + LoRa module + Deadlight client build\n\n### Radio Configuration\n\nFor best Internet gateway performance:\n```\n# In Meshtastic app or CLI\nmeshtastic --set lora.region US --set lora.modem_preset LONG_FAST\nmeshtastic --set lora.tx_power 30  # Maximum (check local regulations)\nmeshtastic --set lora.hop_limit 3  # Adjust for network size\n```\n\n## Usage\n\n### Basic Configuration\n\nEdit `meshtastic.conf`:\n\n```ini\n[core]\nport = 8080\nmax_connections = 50\nlog_level = info\n\n[meshtastic]\nenabled = true\nserial_port = /dev/ttyACM0\nbaud_rate = 115200\nmesh_node_id = 0x12345678  # Your gateway's Meshtastic ID\nfragment_size = 220        # Max payload per packet\nack_timeout = 30000        # 30 seconds for mesh ACKs\nmax_retries = 3\n\n[ssl]\nenable_interception = true\nca_cert = /etc/deadlight/ca/ca.crt\nca_key = /etc/deadlight/ca/ca.key\n\n[network]\npool_max_per_host = 5      # Reuse connections aggressively\npool_idle_timeout = 600    # Keep idle connections longer\nupstream_timeout = 120000  # Allow slow mesh responses\n```\n\n### Client Setup\n\n**On mesh client devices**, configure proxy settings:\n\n```bash\n# Linux/Mac\nexport http_proxy=mesh://gateway-node-id:8080\nexport https_proxy=mesh://gateway-node-id:8080\n\n# Or in applications:\n# HTTP Proxy: gateway-node-id port 8080\n# SOCKS5: gateway-node-id port 8080\n```\n\n**On Android** (using Meshtastic app + ProxyDroid):\n1. Install ProxyDroid\n2. Set proxy to gateway node's mesh ID\n3. Connect Meshtastic app via Bluetooth\n\n### Testing\n\n```bash\n# From mesh client node\ncurl -x mesh://gateway:8080 http://example.com\n\n# Send email via mesh\ncurl -x mesh://gateway:8080 \\\n  --mail-from sender@example.com \\\n  --mail-rcpt recipient@example.com \\\n  --upload-file message.txt \\\n  smtp://smtp.gmail.com:587\n\n# SOCKS5 for SSH over mesh\nssh -o ProxyCommand=\"nc -X 5 -x gateway:8080 %h %p\" user@remote-server\n```\n\n## Configuration\n\n### Optimizing for Mesh Performance\n\n**Bandwidth Conservation**:\n```ini\n[plugins]\n# Enable aggressive compression\ncompressor.enabled = true\ncompressor.min_size = 512\ncompressor.algorithms = gzip,brotli\n\n# Cache aggressively to reduce mesh traffic\ncache.enabled = true\ncache.max_size_mb = 500\ncache.ttl_hours = 24\n```\n\n**Latency Tolerance**:\n```ini\n[meshtastic]\n# Longer timeouts for multi-hop paths\nack_timeout = 60000\nmax_retries = 5\n\n[network]\n# Don't timeout on slow mesh responses\nupstream_timeout = 300000  # 5 minutes\nconnection_timeout = 180000  # 3 minutes\n```\n\n**Priority Shaping**:\n```ini\n[plugins]\nratelimiter.enabled = true\n# Reserve bandwidth for critical services\nratelimiter.priority_high = smtp,imap,dns\nratelimiter.priority_low = http_video,http_images\n```\n\n### Advanced: Multi-Gateway Setup\n\nFor redundancy, run multiple gateways:\n\n```ini\n[meshtastic]\ngateway_mode = true\nannounce_interval = 300  # Announce availability every 5 min\nprefer_local = true      # Route via nearest gateway\nload_balance = true      # Distribute across gateways\n```\n\n## How It Works\n\n### Architecture Overview\n\n```\n┌─────────────┐                  ┌──────────────┐                ┌──────────┐\n│ Mesh Client │                  │   Deadlight  │                │ Internet │\n│   (Phone)   │  LoRa Packets    │   Gateway    │   TCP/   |   IP        │ Services │\n│             ├─────────────────\u003e│              ├───────────────\u003e│          │\n│ Meshtastic  │  (868/915 MHz)   │ - Fragment   │                │  HTTP       │\n│     App     │                  │ - Reassemble │                │  SMTP       │\n│             │\u003c─────────────────┤ - TLS Proxy  │\u003c───────────────┤  IMAP    │\n└─────────────┘                  └──────────────┘                └──────────┘\n                                         │\n                                         │ Also bridges:\n                                         ├─\u003e Other mesh nodes\n                                         ├─\u003e Offline message store\n                                         └─\u003e Satellite uplink (if available)\n```\n\n### Packet Flow\n\n1. **Request Fragmentation**:\n   ```\n   HTTP GET request (1500 bytes)\n   └─\u003e Split into 7 Meshtastic packets (~220 bytes each)\n   └─\u003e Each tagged with sequence number + session ID\n   └─\u003e Sent hop-by-hop through mesh to gateway\n   ```\n\n2. **Gateway Reassembly**:\n   ```\n   Gateway receives packets out-of-order\n   └─\u003e Buffers and sorts by sequence number\n   └─\u003e Detects missing packets, requests retransmit\n   └─\u003e Reassembles into original HTTP request\n   └─\u003e Proxies to Internet normally\n   ```\n\n3. **Response Fragmentation**:\n   ```\n   HTTP response (50KB HTML)\n   └─\u003e Gateway fragments into ~230 packets\n   └─\u003e Sends with flow control (wait for ACKs)\n   └─\u003e Client reassembles and delivers to application\n   ```\n\n### Protocol Detection\n\nDeadlight auto-detects protocols by inspecting initial bytes:\n- `GET / HTTP/1.1` → HTTP handler → Fragment and forward\n- `CONNECT example.com:443` → HTTPS tunnel → TLS interception optional\n- `EHLO` → SMTP handler → Email relay\n- `\\x05` → SOCKS5 handler → Transparent tunneling\n\n### Security Model\n\n**Encryption layers**:\n1. **LoRa PHY**: AES-256 encryption at Meshtastic layer\n2. **TLS**: End-to-end between client and final destination\n3. **Proxy MITM** (optional): Deadlight can terminate TLS for caching/inspection\n\n**Trust model**:\n- Gateway has root CA (can inspect HTTPS if enabled)\n- Mesh uses Meshtastic's channel encryption (PSK)\n- Clients trust gateway CA (install certificate)\n\n**Privacy**: Mesh node IDs are pseudonymous. For operational security in sensitive deployments, use throwaway node IDs and rotate channel keys.\n\n## Real-World Use Cases\n\n### Disaster Response Network\n\n**Scenario**: Earthquake destroys cell infrastructure\n\n**Setup**:\n- Solar-powered Deadlight gateway at field hospital (has satellite uplink)\n- Rescue teams carry Meshtastic handhelds (10km range)\n- Coordinate via email, share maps, update databases\n\n**Result**: Teams stay connected across 50+ square km with zero functioning infrastructure.\n\n### Rural Community Internet\n\n**Scenario**: Village 30km from nearest fiber connection\n\n**Setup**:\n- One gateway node at village center (WiMAX or satellite backhaul)\n- Residents install Meshtastic radios on roofs\n- Multi-hop mesh covers entire valley\n\n**Result**: 100+ households share single Internet connection. Cost: ~$50 per household for radio, no monthly fees.\n\n### Protest/Festival Network\n\n**Scenario**: Large gathering needs coordination without relying on government-controlled networks\n\n**Setup**:\n- Organizers carry Deadlight gateways with LTE failover\n- Attendees use Meshtastic app on phones (Bluetooth to radios)\n- Network disappears when powered down (no logs, no traces)\n\n**Result**: Thousands communicate freely. Network evaporates forensically when disassembled.\n\n### Journalist in Blackout Zone\n\n**Scenario**: Government shuts down Internet during protests\n\n**Setup**:\n- Journalist has Meshtastic radio + Deadlight on laptop\n- Connects to mesh gateway run by colleague 15km away (who has working connection)\n- Files stories via mesh SMTP relay\n\n**Result**: Censorship bypassed. Reports reach editors despite blackout.\n\n## Performance\n\n### Throughput Expectations\n\n**LoRa Physical Layer** (LONG_FAST preset):\n- Raw bitrate: ~5.5 kbps\n- Effective throughput: ~3-4 kbps (after protocol overhead)\n- Latency: 500ms - 5s per hop\n\n**Real-World Application Performance**:\n- **Email**: 10-20 emails/minute (text-heavy)\n- **Web browsing**: 30-60 seconds per page (with caching)\n- **DNS**: ~2 seconds per lookup (cache aggressively!)\n- **API calls**: 5-10 seconds per request\n- **File transfer**: ~400 bytes/sec (~1.4 MB/hour)\n\n**Optimization tips**:\n- Enable compression (3-10x improvement for text)\n- Use image proxies (reduce image sizes before meshing)\n- Cache everything possible (DNS, API responses, static assets)\n- Batch requests (avoid chatty protocols)\n\n### Scaling Considerations\n\n**Single Gateway**:\n- Handles 10-20 concurrent mesh clients comfortably\n- Limited by LoRa airtime regulations (1% duty cycle in EU)\n\n**Multi-Gateway Mesh**:\n- Horizontally scalable (add more gateways = more capacity)\n- Load balances automatically across available gateways\n\n**Bottlenecks**:\n1. LoRa duty cycle (legal limit on transmission time)\n2. Mesh hop count (\u003e4 hops = diminishing returns)\n3. Gateway uplink bandwidth (satellite is typically the constraint)\n\n## Roadmap\n\n### v1.1 (Q1 2026)\n- Adaptive fragmentation (adjust packet size based on mesh conditions)\n- Intelligent retry with exponential backoff\n- Pre-fetching for common resources\n- Android client app (native Deadlight on-device)\n\n### v1.2 (Q2 2026)\n- Multi-gateway coordination protocol\n- Offline message queue (store-and-forward when gateway unreachable)\n- Bandwidth shaping per client/protocol\n- WebRTC signaling over mesh (for peer-to-peer voice/video)\n\n### v2.0 (Future)\n- Full IPv6 support\n- Meshtastic firmware integration (run Deadlight directly on ESP32)\n- Satellite backhaul optimization (Starlink, Iridium)\n- Machine learning for mesh route prediction\n\n## Contributing\n\nThis is a specialized fork of [Deadlight Proxy](https://github.com/gnarzilla/proxy.deadlight). Contributions welcome:\n\n- **Protocol optimizations**: Improve mesh efficiency\n- **Hardware testing**: Validate on different radio platforms\n- **Real-world deployments**: Share your use cases and lessons learned\n- **Documentation**: Especially non-English guides for global use\n\nSee [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.\n\n## Support \u0026 Community\n\n- **Issues**: [GitHub Issues](https://github.com/gnarzilla/deadlight-meshtastic/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/gnarzilla/deadlight-meshtastic/discussions)\n- **Matrix**: `#deadlight-mesh:matrix.org`\n- **Development**: [ko-fi/gnarzilla](https://ko-fi.com/gnarzilla)\n\n## Legal \u0026 Safety\n\n**Radio Regulations**: LoRa operates in license-free ISM bands, but transmission power and duty cycle are regulated. Ensure compliance with your local regulations (FCC Part 15 in US, ETSI EN 300-220 in EU).\n\n**Encryption Export**: This software includes strong cryptography. Check export restrictions if deploying internationally.\n\n**Responsible Use**: This tool can bypass censorship and provide communication in emergencies. It can also be misused. Use ethically and legally. The authors are not responsible for misuse.\n\n**Privacy Notice**: Meshtastic mesh networks are pseudonymous, not anonymous. For operational security in high-risk environments, use proper opsec practices (rotate node IDs, use ephemeral keys, avoid PII in mesh metadata).\n\n## License\n\nMIT License – see [LICENSE](docs/LICENSE)\n\nIncludes:\n- [Meshtastic Protobufs](https://github.com/meshtastic/protobufs) (GPL v3)\n- [nanopb](https://jpa.kapsi.fi/nanopb/) (zlib license)\n\n---\n\n**Status**: testing-ready v1.0.0 | **Maintained by**: [@gnarzilla](https://github.com/gnarzilla)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnarzilla%2Fmeshtastic.deadlight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgnarzilla%2Fmeshtastic.deadlight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnarzilla%2Fmeshtastic.deadlight/lists"}