⚡ WarpGUI

Native, blazingly fast system tray GUI for Cloudflare's WARP on Linux.

---

📑 Table of Contents

• Motivation & Problem Solved
• Installation & Quickstart
• Key Features
• Architecture & Data Flow
• System Tray UI & States
• Development & Build Workflow
• Troubleshooting & FAQ
• License

---

💡 Motivation & Problem Solved

• The Problem: Cloudflare's official WARP client on Linux operates strictly via the terminal (warp-cli). It lacks an official graphical tray monitor or visual connection indicator, forcing users to repeatedly type terminal commands (warp-cli status, warp-cli connect, warp-cli disconnect) with zero real-time visibility into silent network disconnects or daemon status changes.
• The Solution: WarpGUI is a lightweight, native Go system tray utility that provides seamless one-click toggling, real-time daemon state synchronization, animated transition indicators, session logs clipboard export, single-instance process protection, and zero-configuration desktop auto-installation.

---

⚡ Installation & Quickstart

Option 1: Direct Binary Download (Recommended)

Download the standalone executable directly from the latest release:

1. Download: WarpGUI_Linux_x64 (Linux x86_64) | checksums.txt (SHA256)
2. Make Executable & Run:

   chmod +x WarpGUI_Linux_x64
   ./WarpGUI_Linux_x64

3. Zero-Configuration Desktop Integration: On first launch, WarpGUI automatically:
   • Installs the binary to ~/.local/bin/warp-tray.
   • Embeds application icons into ~/.local/share/icons/warp-tray.png.
   • Generates a desktop application menu launcher at ~/.local/share/applications/warp-tray.desktop.
   • Configures automatic login startup at ~/.config/autostart/warp-tray.desktop.

Option 2: Build & Run from Source

If building from source, WarpGUI uses a standard Makefile workflow:

# Clone repository
git clone https://github.com/sudoShikhar/WarpGUI.git
cd WarpGUI

# Setup dependencies and run locally
make setup
make run

---

🚀 Key Features

• ⚡ Zero-Configuration Desktop Integration: Automatically sets up binary paths, desktop menu entries, icons, and user login autostart upon first run.
• 🔄 Seamless Updates: Downloading and running newer binary versions atomically updates ~/.local/bin/warp-tray.
• 🛡️ Single-Instance Protection: Automatically detects and terminates older running instances using /proc executable verification to prevent duplicate tray icons.
• ⏱️ Non-Blocking Async Event Loop: UI event handling and background polling run asynchronously with context timeouts (context.WithTimeout), preventing desktop lag if the daemon becomes unresponsive.
• 💡 Animated Transition Feedback: Dynamic icon blinking indicators during connecting/disconnecting states.
• 📋 Session Logs & Clipboard Export: In-memory rolling log buffer (with memory limits) and one-click "Copy Logs" tray menu item for instant troubleshooting.

---

🏗️ Architecture & Data Flow

flowchart TD
    subgraph UI["1. Desktop Interface"]
        Tray["🖥️ GTK3 System Tray<br>(Status / Connect / Disconnect / Version)"]
        Menu["📋 Context Menu & Clipboard Logs"]
        Tray --> Menu
    end

    subgraph Runtime["2. WarpGUI Runtime Loop"]
        Main["⚡ UI Event Loop<br>(main.go)"]
        Poller["🔄 Passive Status Poller<br>(2s Timer Loop)"]
        Installer["🚀 Desktop Integration & Process Guard<br>(install.go)"]
        Main <--> Poller
        Main --> Installer
    end

    subgraph Backend["3. Cloudflare Daemon Subsystem"]
        CLI["⚙️ Cloudflare warp-cli<br>(Subprocess with Context Timeouts)"]
        Daemon["🛡️ Cloudflare WARP Daemon<br>(warp-svc / systemd daemon)"]
        CLI <--> Daemon
    end

    UI <--> Runtime
    Runtime <--> Backend

Loading

Important

Runtime Prerequisites: WarpGUI requires Cloudflare's official warp-cli client and the warp-svc background daemon running on your system (sudo systemctl status warp-svc).

---

🖥️ System Tray UI & States

Tray Icon / State	Menu Status Title	Toggle Button	Action / Description
🟢 Active	Status: Connected	Disconnect	Cloudflare WARP tunnel is active and protecting DNS/traffic
🟡 Blinking	Status: Connecting...	Connecting... (Disabled)	State transition in progress; prevents rapid duplicate clicks
⚪ Inactive	Status: Disconnected	Connect	WARP connection is currently disconnected
🔴 Inactive	Status: Error	Unavailable (Disabled)	warp-cli timed out or warp-svc daemon is unreachable

---

🛠️ Development & Build Workflow

WarpGUI uses a clean Linux-native Makefile task runner for all development and build operations.

# Display all available targets
make help

# Download and tidy Go dependencies
make setup

# Run static analysis (go vet & staticcheck)
make lint

# Auto-format Go code, organize imports, and chain lint verification
make format

# Run automated test suite with coverage
make test

# Launch the application locally directly from source in-place
make run

# Compile optimized, stripped production binary into builds/
make build

# Remove build outputs and coverage files
make clean

---

❓ Troubleshooting & FAQ

1. Tray icon does not appear or throws GTK/AppIndicator errors

WarpGUI utilizes native GTK3 and Ayatana AppIndicator bindings. Install the required system packages if not already present:

• Ubuntu / Debian / Linux Mint:

  sudo apt install libayatana-appindicator3-1 libgtk-3-0

• Fedora / RHEL:

  sudo dnf install libayatana-appindicator-gtk3 gtk3

• Arch Linux / Manjaro:

  sudo pacman -S libayatana-appindicator gtk3

2. Status displays "Error" or "Unable to connect"

Ensure the Cloudflare WARP systemd daemon is active and registered:

# Check daemon status
sudo systemctl status warp-svc

# Start daemon if inactive
sudo systemctl start warp-svc

# Ensure client is registered
warp-cli registration show || warp-cli register

3. How do I inspect debug logs?

Click the Copy Logs button in the WarpGUI tray menu. The diagnostic log buffer will be copied directly to your clipboard, containing timestamps, status outputs, and connection events.

---

📄 License

Distributed under the GNU General Public License v3.0. See LICENSE for complete terms.

(back to top ↑)