Installation

Choose the parts of WakeLink you need: Android client, ESP32 firmware, CLI tooling, or a full self-hosted relay deployment.

Android App

Note
Requirements:
  • Android 7.0 (API 24) or higher
  • Internet connectivity (mobile data or WiFi)
  • ~12 MB free storage

1 Download APK

Visit the Downloads page on your Android agent and tap Download APK. Wait for the download to complete. Download APK

2 Enable installation from unknown sources

Open your file manager and locate the downloaded wakelink.apk. Tap the file — Android will prompt you to allow installation from unknown sources. Go to Settings → Security → Install Unknown Apps, enable it for your browser or file manager.

3 Install and launch

Return to the file manager and tap Install. Once installed, open WakeLink from your app drawer, tap Sign In or Create Account, grant network permissions, and your registered agents will appear on the home screen.
Note
First Launch Tip: Make sure to grant network permissions when prompted — the app needs internet access to communicate with WakeLink agents.

Build from Source

Build the Android app yourself from the public repository.

1 Install prerequisites

  • Android Studio (latest stable)
  • JDK 17 or higher
  • Android SDK with API level 26+

2 Clone and build

git clone https://git.deadboizxc.org/wakelink/android.git
cd android

# Build release APK
./gradlew assembleRelease

# APK output: app/build/outputs/apk/release/

3 Install on agent

# Via ADB
adb install app/build/outputs/apk/release/app-release.apk
Note
You will need to sign the APK with your own keystore for distribution. See the Android developer documentation for signing instructions.

ESP32 Firmware

Note
Prerequisites:
  • Python 3.7+ — Download Python
  • esptool — installed via pip (see below)
  • USB cable (Micro-USB or USB-C depending on your board)
  • Supported board: ESP32-WROOM-32, ESP32-DevKitC, NodeMCU-32S, or similar

1 Install esptool

pip install esptool

# Confirm the install
esptool.py version
# Expected: esptool.py v4.x.x

2 Download firmware

Grab the latest wakelink-esp32.bin from the Downloads page.

3 Erase and flash

# Step 1: Erase existing flash (recommended for clean install)
esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash

# Step 2: Flash the WakeLink firmware
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 \
  write_flash 0x0 wakelink-esp32.bin

# Windows users — replace /dev/ttyUSB0 with your COM port, e.g.:
esptool.py --chip esp32 --port COM3 --baud 460800 \
  write_flash 0x0 wakelink-esp32.bin
Warning
If flashing fails, hold the BOOT button on the ESP32 while running the flash command, releasing it once output begins.
Note
After a successful flash, the ESP32 reboots and broadcasts a WakeLink-Setup-XXXX WiFi hotspot for initial configuration. See First Agent Setup for the next steps.

Self-Hosted Server

Run your own WakeLink backend instead of using the hosted cloud service. Requires a server or VPS reachable from the internet.

Note
Requirements:
  • Python 3.10+
  • Git
  • A publicly reachable server (VPS, home server with port forwarding, etc.)
  • Optional: PostgreSQL or SQLite (SQLite used by default)

Pre-built Binary (Python/uvicorn)

1 Clone and install

git clone https://git.deadboizxc.org/wakelink/relay-ce.git
cd relay-ce

# Create a virtual environment
source .venv/bin/activate        # Linux / macOS
# .venv\\Scripts\\activate.bat    # Windows

pip install -r requirements.txt

2 Configure environment

cp .env.example .env
# Edit .env with your settings:

WAKELINK_SECRET_KEY=your-secret-key-here
WAKELINK_DATABASE_URL=sqlite:///./wakelink.db
WAKELINK_REDIS_URL=redis://redis:***@wakelink-postgres:5432/wakelink

3 Launch services

# Run the deployer (clones all service repos and starts containers)
./install.sh

# Check relay server logs
docker logs -f wakelink-relay

# Verify all services are running
docker ps
Note
See the Self-Hosted guide for full SSL/TLS, database, and security configuration.

CLI Tool

The WakeLink CLI lets you manage agent entries and send commands from the terminal.

1 Install

pipx install wakelink-cli
# or
pip install wakelink-cli

wakelink --help

2 Register an agent

# Local TCP agent
wakelink add desk --ip 192.168.1.50 --token "$AGENT_TOKEN"

# Cloud relay entry
wakelink register esp32-cloud \
  --token "$AGENT_TOKEN" \
  --mode cloud \
  --api-url https://wakelink-project.org/api/v1

3 Run commands

wakelink list
wakelink ping desk
wakelink info desk
wakelink wake desk AA:BB:CC:DD:EE:FF

4 Use account commands (optional)

export WAKELINK_SERVER=https://wakelink-project.org
export WAKELINK_TOKEN=wl_xxxxxxxxxxxxxxxxxxxx

wakelink account info
wakelink account telegram-link

Next Steps

Continue reading