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

1 Sign in

Authenticate via the dashboard, mobile app or CLI — credentials are exchanged for a long-lived API token (see Token Rotation ).

2 Pair a agent

Flash the agent firmware and enter the pairing TOTP from the dashboard to register the ESP32 as a trusted agent (see First Agent Setup ).

3 Issue 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.

4 Agent 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.

5 Status & telemetry

Status flows back up the same WebSocket. The dashboard, NTFY mobile push and Telegram bot surface last-seen timestamps and wake history.

Note

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, agent & session bookkeeping, EWSP framing.
Dashboard	Next.js 16 / React 19	Web UI for account, agents, sessions, tokens, billing portal.
Telegram Bot	Python / aiogram	Login deep-links, password reset, /agents list.
Mailer	Python / FastAPI	One endpoint (/send) with four backends for verification, reset, reports.
NTFY	Go	Push notifications for offline / mobile delivery of wake events.
Postgres	PostgreSQL 16	Primary store: users, agents, sessions, audit log.
Redis	Redis 7	Cache, session/queue store, rate-limit counters.
Proxy	nginx + Certbot	Reverse-proxy. Terminates TLS, routes /, /app, /api, /wss, /docs.
Deployer	Bash + Docker Compose	Curated source bundles + Compose stacks for one-command self-hosting.

Note

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, agents, 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 <agent> from any shell. See CLI Guide .

Multiplatform Client SDK (work in progress)

Kotlin Multiplatform module that aims to share networking, EWSP bindings and agent-management code across Android, iOS and Desktop (Compose Multiplatform). The stable Android client is the reference consumer.

Agents & On-agent 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, agents, 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, /wss, /docs. Legacy app. / api. subdomains 301-redirect to the consolidated routes.

Note

Every service has its own README and SECURITY.md in the source repository — start at git.deadboizxc.org/wakelink for deeper, per-component documentation.

Security — EWSP encryption and blind relay design
Self-Hosted — deploy the full stack yourself
API Reference — REST, WebSocket, and EWSP protocol