pclink 3.1.0

Cross-platform desktop app for secure remote PC control and management, featuring a lightweight built-in WebUI and API for local or remote access.

---

PCLink is a modern, web-first application for secure remote PC control from mobile devices.
It features a FastAPI server, responsive web interface, and lightweight system tray.

Created by Azhar Zouhir / BYTEDz

📱 Need the mobile app? Get it at Google Play Store

---

⚠️ Important Notice for Linux Users

If you have PCLink v2.3.0 or earlier installed, you must uninstall it before upgrading due to broken FPM packaging:

# Download and run the force purge script
wget https://raw.githubusercontent.com/BYTEDz/PCLink/main/force-purge-pclink.sh
chmod +x force-purge-pclink.sh
sudo ./force-purge-pclink.sh

This script safely removes broken package installations and cleans up your system. New installations from v2.4.0+ use NFPM and don't have this issue.

What Changed?

• v2.3.0 and earlier: Used FPM (Ruby-based) packaging with broken maintainer scripts
• v2.4.0+: Uses NFPM (Go-based) packaging with reliable installation/removal
• Benefits: Better cross-platform support, more reliable package management, both DEB and RPM support

---

🗃️ Documenstation

Complete documentation is available in the PCLink Wiki

• 📖 Getting Started - Installation and first-time setup
• 🏗️ Server Architecture - How PCLink works
• 🔌 API Endpoints - Complete API reference
• 🌐 Web UI Guide - Using the web interface
• 🛠️ Building & Development - Build from source
• 🤝 Contributing Guide - How to contribute
• ⚡ Quick Reference - Commands and tips

---

🚀 Features

🌐 Web-First Interface

• Modern Web UI: Responsive, dark-themed control panel
• Real-time Updates: WebSocket-powered live data
• QR Code Pairing: Visual device pairing with actual QR codes
• Cross-Platform: Works on any device with a browser
• No Dependencies: Zero Qt/GUI library requirements

🔧 Core Functionality

• Remote Control: File browser, process manager, terminal access
• Media & Input: Media playback, keyboard/mouse input, clipboard sync
• System Actions: Shutdown, restart, volume control, system info
• Screen Capture: Remote screenshots
• Device Management: Pairing, approval, and revocation

🔒 Security & Authentication

• Web UI Authentication: Password-protected interface with sessions
• HTTPS Only: Auto-generated self-signed certificates
• API Key Authentication: Secure device access
• Session Management: 24-hour sessions with automatic cleanup
• Secure Pairing: QR code-based device authentication

---

💻 System Requirements

✅ Supported Platforms

• Windows 10 or later (Windows 10/11) - Full support with system tray and power management
• Linux - Debian/Ubuntu, Fedora, and other distributions with systemd
  • Best experience on X11-based desktops (Cinnamon, XFCE, KDE, MATE)
  • Wayland support with some limitations (see Known Limitations)

⚠️ Windows Users: PCLink requires Windows 10 or later. Earlier versions (Windows 7, 8, 8.1) are not supported.

🔧 Requirements

• Python 3.8+ (automatically handled in packaged installations)
• Network access for mobile device communication
• Administrator privileges for power management features (optional)

---

📱 Mobile App Required

The server requires the companion mobile app:

• 🌐 Official Website
• 📱 Google Play
• 🍎 iOS: Coming soon

---

🛠️ Installation & Setup

🚀 Recommended: Native Packages

Windows (10 or later)

1. Download the latest .exe installer from Releases
2. Run the installer with administrator privileges
3. PCLink will be available in Start Menu and system tray

Note: Windows 10 or later is required. Earlier Windows versions are not supported.

Linux (Ubuntu/Debian)

1. Download the latest .deb package from Releases
2. Install: sudo apt install ./pclink_*.deb
3. Start: pclink or find in applications menu

Linux (Fedora/RHEL)

1. Download the latest .rpm package from Releases
2. Install: sudo dnf install ./pclink-*.rpm
   • This will automatically install all required dependencies
3. Start: pclink or find in applications menu

Note: The RPM package includes smart dependency handling that automatically installs required packages like python3-devel, wl-clipboard, and gnome-screenshot on Fedora.

Note: Packages from v2.4.0+ use NFPM packaging system for better reliability.

🐍 Python Installation

System Dependencies (Linux Only)

# Install all required system dependencies first
sudo apt update
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-appindicator3-0.1 gir1.2-gtk-3.0 python3-tk python3-dev python3.12-venv gcc build-essential

Install PCLink

# Option 1: Install from source
pip install -e .

# Option 2: Install directly from GitHub
pip install git+https://github.com/BYTEDz/PCLink.git

🎛️ Usage

# Start PCLink (opens web interface automatically)
pclink

# Background/startup mode (system tray only)
pclink --startup

# Don't auto-open browser
pclink --no-browser

# Test power command permissions (Linux)
test-power-permissions

🔧 First Time Setup

1. Set Web UI Password: Access https://localhost:38080/ui/ and create a password
2. Pair Mobile Device: Scan the QR code with the PCLink mobile app
3. Configure Startup: Enable "Start with system" in web UI settings

---

👨‍💻 Development

🛠️ Development Setup

# Linux: Install system dependencies first
sudo apt update
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0 python3-tk python3-dev python3.12-venv gcc build-essential libgirepository1.0-dev libcairo2-dev pkg-config

# Clone repository
git clone https://github.com/BYTEDz/PCLink.git
cd PCLink

# Create virtual environment
python3 -m venv pclink-env
source pclink-env/bin/activate  # Linux/macOS
# or: pclink-env\Scripts\activate  # Windows

# Install PCLink with all dependencies (runtime + development)
pip install -e ".[dev]"

# Or install only runtime dependencies
pip install -e .

# Install pre-commit hooks
pre-commit install

# Run PCLink
python -m pclink

# Run tests
pytest

📦 Building Packages

Linux .deb/.rpm Packages

# Install NFPM dependencies
sudo apt update
sudo apt install build-essential dpkg-dev rpm

# Install NFPM (package manager)
NFPM_VERSION="2.40.0"
wget -O nfpm.deb "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_amd64.deb"
sudo dpkg -i nfpm.deb
rm nfpm.deb

# Install minimal Python build dependencies (no runtime deps needed)
pip install wheel setuptools build pyyaml

# Build packages (creates both .deb and .rpm)
python scripts/build.py --format nfpm

Note: NFPM builds create both DEB and RPM packages simultaneously. The build script creates a wheel and packages it with proper dependency declarations for the package manager to handle.

Windows Packages

# With virtual environment activated
python scripts/build.py --format portable    # ZIP archive
python scripts/build.py --format onefile     # Single EXE
python scripts/build.py --format installer   # Windows installer

🔧 Build Troubleshooting

Missing PyInstaller Error (for Windows/portable builds)

# Install development dependencies
pip install -e ".[dev]"

# Then retry building
python scripts/build.py --format portable

Missing NFPM Dependencies (Linux package builds)

If you see [ERROR] Missing NFPM dependencies:

# Ubuntu/Debian:
sudo apt update
sudo apt install build-essential dpkg-dev rpm

# Install NFPM
NFPM_VERSION="2.40.0"
wget -O nfpm.deb "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_amd64.deb"
sudo dpkg -i nfpm.deb
rm nfpm.deb

# Fedora/RHEL:
sudo dnf install rpm-build gcc make
# Then install NFPM from GitHub releases or use Go

# Arch Linux:
sudo pacman -S base-devel
# Then install NFPM from AUR or GitHub releases

# Install minimal Python build dependencies
pip install wheel setuptools build pyyaml

# Then retry build
python scripts/build.py --format nfpm

---

🔧 Troubleshooting

Common Issues

Compilation Errors (Linux)

If you see "Python.h: No such file or directory":

# Ubuntu/Debian
sudo apt install python3-dev gcc build-essential

# Fedora/RHEL
sudo dnf install python3-devel gcc

# Then retry installation
pip install -e .

Dependency Errors (Linux)

For "Dependency 'girepository-2.0' is required but not found" or similar errors:

# Install comprehensive system dependencies
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0 python3-tk libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0

# Install PyGObject
pip install PyGObject

Feature Availability

Feature	Always Available	Optional Dependencies
Web UI	✅	-
API Server	✅	-
File Management	✅	-
Process Control	✅	-
Screenshots	✅	-
System Tray	✅ (with fallback)	pystray, PyGObject (Linux native)
Input Control	✅ (with fallback)	pynput

Note: PCLink gracefully falls back to alternative implementations if dependencies are missing. All core functionality remains available.

Known Limitations

GNOME Desktop (Wayland)

• System Tray: GNOME removed native tray support. Install the AppIndicator extension to enable tray icons.
• Wayland Support: Screenshot and clipboard work via gnome-screenshot and wl-clipboard (auto-installed on Fedora RPM).
• Input Control: Mouse/keyboard remote control requires additional permissions on Wayland.

Fedora-Specific

• Use sudo dnf install ./pclink-*.rpm instead of rpm -i for automatic dependency resolution.
• Required packages are automatically installed during setup.

---

🏗️ Architecture

🌐 Web-First Stack

• Frontend: Modern HTML5/CSS3/JavaScript with WebSocket
• Backend: FastAPI + Uvicorn ASGI server
• Authentication: Session-based with PBKDF2 password hashing
• System Tray: Cross-platform pystray (lightweight)
• Security: HTTPS + API keys + web authentication
• Packaging: Minimal dependencies, easy deployment

📁 Project Structure

src/pclink/
├── api_server/      # FastAPI routers + WebSocket handlers
├── core/            # Controller, auth, config, security
├── web_ui/          # Modern web interface (HTML/CSS/JS)
│   └── static/      # Web assets, authentication pages
└── assets/          # Icons and resources

🛠️ API Endpoints

Public:

• /ui/ - Web interface (with auth)
• /auth/* - Authentication endpoints
• /status - Server health check

Protected (API Key):

• /system/* - Power, volume, processes
• /info/* - System and media information
• /input/* - Remote keyboard/mouse control
• /media/* - Playback control
• /files/* - File browser and operations
• /terminal/* - WebSocket shell access
• /ws - WebSocket for real-time communication

Web UI (Session Auth):

• /devices - Connected device management
• /logs - Server log viewing
• /qr-payload - QR code generation data

---

🔒 Security

🌐 Web Interface Security

• Password Authentication: PBKDF2-hashed passwords with salt
• Session Management: Secure HTTP-only cookies with 24-hour timeout
• IP Validation: Session tied to client IP address
• Automatic Cleanup: Expired sessions automatically removed

📱 Mobile Device Security

• HTTPS Only: Encrypted communication with auto-generated certificates
• API Key Authentication: Unique keys per device
• Device Approval: Manual pairing approval required
• QR Code Pairing: Secure visual pairing process
• Device Revocation: Instant access removal capability

🛡️ System Security

• Single Instance: Prevents multiple server conflicts
• Local Certificates: Self-signed HTTPS certificates
• No HTTP Fallback: HTTPS enforcement
• Secure Defaults: All security features enabled by default

---

📄 License

GNU AGPL v3 – Free to use, modify, and distribute. ⚠️ Proprietary services must open-source modifications. For commercial licensing, contact BYTEDz.

---

📞 Support

• Support: [e-mail]
• Website: bytedz.xyz/products/pclink
• Developers: GitHub Issues • Discussions

---

� Mahintainers

Azhar Zouhir Creator & Lead Developer 📧 💻

---

🕊️ Free Palestine • 🇩🇿 Made with ❤️ in Algeria