Architecture
Map the WakeLink platform across relay services, clients, firmware agents, and the EWSP protocol boundaries between them.
Overview
WakeLink lets you wake any LAN-attached machine from anywhere on the Internet through an end-to-end encrypted relay. A small agent (ESP32 board or software emulator) sits inside your network and translates relayed commands into Wake-on-LAN magic packets. A relay brokers connections between clients and agents without ever seeing the wake payloads in plaintext.
Data Flow
1Sign in
Authenticate via the dashboard, mobile app or CLI — credentials are exchanged for a long-lived API token (see Token Rotation).
2Pair a device
Flash the agent firmware and enter the pairing TOTP from the dashboard to register the ESP32 as a trusted agent (see First Device).
3Issue a wake command
A client (CLI / Android app) opens an end-to-end encrypted EWSP session through the relay and sends the wake frame to the agent. The relay only forwards opaque ciphertext — it has no wake endpoint of its own.
4Agent decrypts & wakes
The agent decrypts the frame using its session key and emits the magic packet on the local network to the target MAC address.
5Status & telemetry
Status flows back up the same WebSocket. The dashboard, NTFY mobile push and Telegram bot surface last-seen timestamps and wake history.
The relay never learns the wake payload — only the destination agent and encrypted frame metadata are visible to the server.
Server Components
Each service is its own repository, deployable independently, and has a dedicated entry in the Licenses page.
| Component | Stack | Role |
|---|---|---|
Relay (CE) | Python 3.11 / FastAPI / WebSockets | Core HTTP + WSS API, auth, device & session bookkeeping, EWSP framing. Free / self-hosted. 10 devices per user by default. |
Dashboard | Next.js 16 / React 19 | Web UI for account, devices, agents, sessions, tokens, billing portal. |
Relay Admin Panel | Next.js | Operator-only console: users, agents, audit log, environment health. |
Telegram Bot | Python / aiogram | Login deep-links, password reset, /devices list. |
Mailer | Python / FastAPI | One endpoint ( /send) with four backends: Resend HTTP, SMTP relay, direct MX, log-only. Used for verification, reset, reports. |
NTFY | Go (wraps upstream ntfy.sh) | Push notifications for offline / mobile delivery of wake events. |
Postgres | PostgreSQL 16 image | Primary store: users, devices, agents, sessions, audit log. |
Redis | Redis 7 image | Cache, session/queue store, rate-limit counters. |
Monitoring | Prometheus + Grafana | Scrape config + "WakeLink Overview" dashboard. App, infra and wake-command metrics. |
Proxy | nginx + Certbot | Reverse-proxy in front of the whole stack. Terminates TLS, routes /, /app, /api, /wss, /docs. |
Billing (EE) | Closed-source service | Stripe / subscription management for the Enterprise tier. Optional. |
Deployer | Bash + Docker Compose | Curated source bundles + Compose stacks for one-command self-hosting. |
The full self-hosted setup is documented step-by-step on the Self-Hosted page.
Client Libraries & Apps
End-user code lives under clients/ and ships with permissive Apache-2.0
licensing so it can be embedded freely in third-party software.
Android Client
Native Android app written in Kotlin with Jetpack Compose. JNI binding to the C EWSP core. Manages account, devices, push subscriptions and one-tap wake. See Android App Guide.
Command-Line Interface
Python CLI (wakelink) suitable for scripting, cron and CI/CD pipelines:
authenticate once, then wakelink wake <device> from any shell. See
CLI Guide.
Multiplatform Client SDK (work in progress)
Kotlin Multiplatform module that aims to share networking, EWSP bindings and device-management code across Android, iOS and Desktop (Compose Multiplatform). The stable Android client is the reference consumer.
Agents & On-Device Code
ESP32 Firmware
C / Arduino firmware that runs on a cheap ESP32 board sitting on your LAN. Maintains a persistent TLS WebSocket to the relay, validates EWSP frames, emits WoL magic packets to the requested target MAC. Supports OTA updates (see OTA).
Agent Emulator
Software emulator that mirrors the firmware's networking surface — a relay WebSocket client and a direct TCP listener (port 99) speaking line-delimited EWSP JSON. Used for testing the rest of the stack without flashing hardware, and as the reference fixture in CI.
Protocols
REST API
OpenAPI 3 spec. Bearer-token auth. Endpoints for account, agents, devices, sessions, releases, billing. See REST API Reference.
WebSocket
Two flavours: a client-facing WSS for the dashboard / app, and an agent-facing WSS that carries EWSP frames. See WebSocket Protocol.
EWSP — Encrypted Wire Session Protocol
WakeLink's bespoke E2E protocol. Pure-C reference library lives at
lib/ewsp/ (no external crypto dependencies).
| Property | Detail |
|---|---|
AEAD | XChaCha20-Poly1305 |
Key exchange | X25519 ECDH (forward-secret session keys) |
KDF | HKDF-SHA256 |
Authentication | HMAC-SHA256 mutual handshake + TOTP for pairing |
Replay protection | Monotonic nonce + sequence window per session |
Full wire format and handshake state machine on the EWSP Protocol Spec page.
Deployment & Tooling
| Mode | Description |
|---|---|
Single-host | One ./install.sh from the deployer repo — clones all service repos and starts the full stack. Suited for home labs and small teams. |
Production | Same compose stack behind wakelink-proxy (or system-wide nginx), with TLS via Certbot, monitoring enabled and external Postgres backups. |
Path routing | Entire stack served from one domain under path prefixes — /, /app, /api, /docs. Legacy app. / api. subdomains 301-redirect to the consolidated routes. |
Every service has its own README and SECURITY.md in the source
repository — start at github.com/wakelink for
deeper, per-component documentation.