🛡️ PC Remote Sentinel & Multi-PC Fleet Commander

A secure, cross-network multi-PC remote management, surveillance, and automation system controlled entirely through a single Telegram Bot.
Monitor, control, diagnose, and automate any number of Windows computers (home desktop, work laptop, gaming rig, remote servers, or a fleet of workstations) from your phone anywhere in the world — across local LAN, mobile hotspots, 4G/5G tethering, or firewalled networks.

---

🌟 Why PC Remote Sentinel?

Traditional remote desktop tools require port forwarding, static public IPs, complex VPN setups, or expensive subscription licenses. PC Remote Sentinel solves this with a modern, serverless architecture:

1. One Central Bot for All Your PCs (/pcs): Seamlessly switch between any registered computer with interactive Telegram inline buttons.
2. Works Everywhere (Cross-Network Cloud Relay): Built-in MQTT over TLS with AES-256-GCM encryption punches through Carrier-Grade NAT (CGNAT), phone hotspots, hotel Wi-Fi, and corporate firewalls without configuring routers.
3. Double-Click USB Pendrive Installer (install.bat): Plug a USB drive into any PC (even brand-new out of the box), double-click, and it automatically sets up Python, creates a silent boot task, and connects to your bot in under 15 seconds.
4. Completely Silent & Background Operation: Runs invisibly via Windows Task Scheduler. No command prompt windows, no taskbar icons, and no system tray clutter.
5. Direct Media Transport: High-resolution screenshots and video recordings upload directly to Telegram's cloud API, bypassing intermediary servers for lightning-fast delivery.
6. Anti-Timeout & Network Resilience Shield: Engineered specifically for high-latency, unstable cellular hotspots, and packet-loss prone connections with automated retries, local loopback routing, dynamic JPEG compression, and live /net ping diagnostics.

---

🏗️ Architecture

                       ┌────────────────────────┐
                       │   Owner's Telegram     │
                       │   (Phone or Desktop)   │
                       └───────────▲────────────┘
                                   │
                     Telegram API  │  Bot Commands
                     (Media & UI)  │  (/start, /pcs, etc.)
                                   ▼
                       ┌────────────────────────┐
                       │   Central Telegram Bot │
                       │    (Fleet Commander)   │
                       └───────────┬────────────┘
                                   │
              MQTT over TLS (Port 8883 / 443 WSS)
              AES-256-GCM Encrypted with FLEET_SECRET
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ Primary Desktop  │     │ Work Laptop      │     │ Remote Server    │
│ Home Wi-Fi       │     │ Mobile Hotspot   │     │ 4G USB Modem     │
│ (Local Subnet)   │     │ (CGNAT / 4G / 5G)│     │ (CGNAT / Remote) │
└────────┬─────────┘     └────────┬─────────┘     └────────┬─────────┘
         │                        │                        │
         └────────────────────────┼────────────────────────┘
                                  ▼
                     Direct Telegram Bot API
                     (Screenshots, Videos, Audio)

---

✨ Features & Capabilities

🖥️ Fleet Management & Multi-PC Switching

• Interactive PC Selector (/pcs, /start): View all registered machines with live online/offline indicators and connection badges (e.g. 🟢 Work-Laptop (Mobile Hotspot) or 🟢 Home-PC (Wi-Fi)).
• Auto-Discovery: Newly installed computers automatically appear in your Telegram menu the moment they boot.
• Last Will & Testament (LWT): If a computer is unplugged or loses network connection, your bot immediately updates its status to 🔴 Offline.

📊 System Diagnostics & Surveillance

• Real-time Diagnostics (/status): CPU utilization, RAM usage, disk storage, battery state, active window title, and system uptime.
• Desktop Screenshots (/shot, /screenshot): Instant high-resolution snapshot of active monitors sent directly to Telegram.
• Webcam Surveillance (/webcam, /record_webcam): Instant photo snapshot or short security video clip (10s/30s) from connected webcams.
• Multi-Duration Screen Recorder (/record_screen): Interactive duration picker for 10s, 20s, 30s, 40s, 50s, 1 min, or 2 mins of on-screen desktop action into an MP4 video file.
• Upgraded Live Screen Casting (/cast, /stream):
  • Cross-Network Global Access: Streams reliably across separate networks, cellular data (4G/5G), and CGNAT via automated Cloudflare Quick Tunnels (https://*.trycloudflare.com) with zero port forwarding.
  • Dual-Engine Web Player: Smooth MJPEG video streaming + resilient Turbo Snapshot Fallback with client-side mobile watchdog (auto-reconnects if cellular signal dips).
  • Interactive Remote Controls: Control virtual desktops, inspect ping latency/FPS HUD, and capture high-res snapshots directly from your phone's browser.
  • In-Chat Live Radar: Rapid refreshing photo frames streamed directly inside your Telegram chat over the cloud relay.

🪟 Desktops & Windows Application Switching

• Dedicated Remote Control (/desktop, /windows, /switch): Switch, create, or inspect Windows Virtual Desktops and cycle or focus active application windows with 1 tap from Telegram or the live web stream player.
• Active Window Selection: Tap any running application from the interactive Telegram keyboard or select it from the Live Stream dropdown to bring it directly to the front (even if minimized).
• Fast Window Cycling:
  • [◀ Alt+Tab] (Cycle forward)
  • [Alt+Tab ▶] (Cycle backward with Shift)
  • Direct Command: /switch brave, /switch code, /switch spotify
• Virtual Desktop Navigation:
  • [◀ Prev Desktop] (Win + Ctrl + Left)
  • [Next Desktop ▶] (Win + Ctrl + Right)
  • [➕ New Desktop] (Win + Ctrl + D)
  • [🪟 Task View] (Win + Tab)
  • [❌ Close Desktop] (Win + Ctrl + F4)
• Safe Modifier Handling: Fully isolated hardware scan-code events with guaranteed modifier key release in finally blocks to eliminate sticky keys.
• Instant Lock (/lock or buttons): Locks the Windows workstation session immediately.
• Power Management: Put PC to sleep, turn off monitors, turn on/wake monitors (/monitor on), reboot, or schedule shutdown timers (15m, 30m, 60m).

📋 Process Manager & Terminal

• Process Viewer (/top): Interactive list of top CPU and memory consuming processes with live refresh.
• Process Killer (/kill <name_or_pid>): Terminate frozen applications or games remotely. Features a built-in Process Safety Shield that blocks blanket killing of python.exe by name (safeguarding your trading bots, background automation, and other Python tools) and prevents terminating critical Windows OS processes or Sentinel itself.
• Remote Terminal (/cmd <command>): Execute Windows shell commands remotely with automatic token masking.

🔊 Audio, TTS & Speaker Controls

• Text-to-Speech (/say <text>): Speak any message aloud through PC speakers using native Windows speech synthesis.
• Voice Note Speaker Playback: Send any voice note or audio file (.ogg, .mp3, .wav) to play your actual voice directly through the PC speakers.
• PC Alarms & Timers (/alarm [time] [label]): Set countdown timers or specific clock alarms with siren alerts and speech synthesis.
• Media Player Controls: Play, pause, skip tracks, volume up/down, and mute for Spotify, YouTube, Chrome, VLC, and media players.

📁 Remote File Explorer & Clipboard

• Interactive File Explorer (/get, /files, /browse, /explore):
  • No Need to Memorize Paths: Sending /get or /files without arguments launches an interactive visual file browser right inside Telegram starting at your Desktop.
  • Visual Directory Navigation: Tap any folder button ([📁 Folder Name]) to navigate inside, tap [⬆️ Up] to go to the parent directory, or tap [🔄 Refresh] to re-scan.
  • Smart File Identification: Displays custom emojis for documents (📄), images (🖼️), videos (🎥), audio (🎵), archives (📦), executables (💻), and scripts (⚙️) with human-readable file sizes.
  • 1-Tap Direct Downloads: Tap any file button ([📄 document.pdf (2.4 MB) ⬇️]) to instantly download and deliver the file directly to your Telegram chat (with 50MB safety check).
  • Quick Access Shortcuts ([🏠 Quick Access]): 1-tap jump to system drive partitions (💻 Drive (C:), 💻 Drive (D:)) or core user folders (Desktop, Downloads, Documents, Pictures, Sentinel Recordings).
  • Smart Path Support: Send /get C:\MyFolder to open the explorer at that folder, or /get C:\path\file.txt to directly fetch the file.
• File Dropper: Send any document, photo, or script to the bot to automatically save it in the PC's downloads/ folder.
• Clipboard Sync (/clip <text>, /getclip): Read or push text directly to and from the Windows clipboard.
• Storage Cleaner (/clean): Audit and clean up cached recordings and downloads with explicit confirmation.

🛡️ Anti-Timeout & Network Resilience Shield

• Engineered for High Latency & Unstable Connections: Built specifically to survive bad internet, weak mobile hotspots, packet drop, 3G/4G/5G tethering, and cellular CGNAT environments where commands frequently time out.
• Intelligent Telegram API Retries (safe_telegram_call): Automatically intercepts transient timeouts, connection resets, and Telegram flood limits (RetryAfter) with exponential backoff retry cycles and extended 60-second read/write timeouts.
• Direct Local HTTP Loopback (127.0.0.1): Host PC commands automatically detect local residence and bypass cloud brokers and internet routing entirely, guaranteeing 0ms ping latency and zero cloud dependency.
• Automatic JPEG Screenshot Compression: High-resolution screenshots automatically compress oversized PNGs (>400KB) into optimized JPEG format (quality 85) on the agent before transmission, slashing upload sizes by 90–95% (e.g. from 4MB to ~200KB) for instantaneous mobile delivery.
• Self-Healing Cloud Relay: Commander Relay automatically buffers and waits up to 6.0 seconds for broker reconnection during transient network blips and automatically retries timed-out commands with QoS 1 confirmation.
• Real-Time Network Diagnostics (/net, /ping): Tap the new "🌐 Network Ping" button or type /net to measure live roundtrip Telegram API latency in milliseconds, MQTT cloud broker connection health, and target PC reachability with color-coded connection ratings.
• Immediate Typing Feedback: Emits immediate ChatAction.TYPING and ChatAction.UPLOAD_PHOTO signals so you always know a command is being processed, even over high-latency connections.

🔒 Enterprise Security Architecture

• User Whitelist Enforcement: Only numeric Telegram user IDs configured in AUTHORIZED_USER_IDS can communicate with the bot.
• Intruder Alerts: Unrecognized users are blocked immediately, and an alert with their Telegram ID and username is dispatched to the owner.
• Process Isolation & Trading Bot Protection: Built-in safeguards strictly prevent accidental termination of user trading bots, other running Python applications, or critical Windows OS system services (csrss.exe, lsass.exe, smss.exe, etc.). Blanket termination of Python by process name is strictly blocked.
• Strict Directory & Path Traversal Isolation: File deletion (/clean) and file explorer operations strictly validate paths within whitelisted directories, preventing any access or modification to sensitive system directories or files used by other processes.
• AES-256-GCM End-to-End Encryption: All MQTT relay messages and command payloads are encrypted with your shared FLEET_SECRET.
• Optional PIN Lock: Require /login <PIN> with automatic session timeout and rate limiting.

---

🚀 Quick Start Guide

Step 1: Set Up Your Telegram Bot

1. Open Telegram and message @BotFather.
2. Send /newbot, choose a name and username, and copy your Bot Token.
3. Message @userinfobot in Telegram to find your numeric User ID (e.g. 6513180621).

Step 2: Configure Master Settings

1. Clone the repository:

   git clone https://github.com/Mazonia/pc-controller-bot.git
   cd pc-controller-bot

2. Copy the template and edit your .env:

   cp .env.example .env

   Fill in your values:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
   AUTHORIZED_USER_IDS=6513180621

3. Copy the deploy template for your USB pendrive:

   cp deploy_config.env.example deploy_config.env

   Fill in your FLEET_SECRET, TELEGRAM_BOT_TOKEN, and AUTHORIZED_USER_IDS.

Step 3: Run the Fleet Commander Bot

You have three flexible ways to run your Commander Bot 24/7:

📱 Option A: Android Phone (24/7 Always-On via Termux) — Recommended

Because smartphones stay powered and connected to Wi-Fi/4G 24/7, you can run the Commander Bot directly on your Android phone!

1. Install Termux (free from F-Droid or GitHub Releases).
2. Open Termux and clone the repo:

   pkg update -y && pkg install -y git python
   git clone https://github.com/Mazonia/pc-controller-bot.git
   cd pc-controller-bot

3. Run the automated setup script:

   bash termux_setup.sh

4. Enter your .env tokens (nano .env) and launch the bot:

   nohup python bot.py > bot.log 2>&1 &

   The script activates termux-wake-lock so Android never suspends your bot when the phone screen is off!

☁️ Option B: Free 24/7 Cloud Server (Render / Railway / Docker) — Zero Phone Battery

Run the Commander Bot 24/7 in the cloud with zero hardware maintenance:

Via Render.com (Free Tier):

1. Sign up at Render.com and click New + → Blueprint.
2. Connect your GitHub repository (Mazonia/pc-controller-bot). Render automatically detects render.yaml.
3. Enter your TELEGRAM_BOT_TOKEN, AUTHORIZED_USER_IDS, and FLEET_SECRET when prompted.
4. Click Apply. Render will build and run your bot 24/7 continuously.

Via Docker / Home Server / VPS:

docker compose up -d

Zero phone battery drain, 99.99% uptime, and instant access from anywhere via your Telegram app.

💻 Option C: Windows Main PC / Laptop (Auto-Start on Boot)

Run the Commander Bot on your local Windows PC:

1. Auto-Start on Windows Boot/Logon (Recommended):

   • Double-click setup_autostart.bat.
   • It automatically registers a silent Task Scheduler task and Startup shortcut.
   • The bot will now run invisibly in the background every time Windows boots! (To disable later, double-click remove_autostart.bat).

2. Run Manually:

   • With visible terminal: Double-click run.bat (or python bot.py).
   • Hidden background mode: Double-click start_hidden.vbs.

---

🔄 Redundancy & Offline Self-Healing

What happens if your Main PC or Commander server goes offline?

• 100% Autonomous Monitored PCs: Each target PC runs agent.py as an independent background process. They never depend on the main PC being turned on. Local timers, scheduled alarms, speakers, and security rules continue functioning normally on each target PC.
• MQTT Retained Telemetry (retain=True): Target PCs publish heartbeats and system states with retain=True to the secure cloud broker.
• Instant Synchronization on Boot: The exact second your Main PC (or phone) powers on and connects to the internet:
  1. bot.py connects to the broker and subscribes to your fleet topic.
  2. The cloud broker immediately flushes the retained status of all online PCs in <50 milliseconds.
  3. You instantly receive a Telegram alert listing all online PCs with their live IP and network badges.
  4. You immediately regain full interactive control over your entire fleet.
• Automatic Last Will & Testament (LWT): If any monitored PC loses power or drops offline while you are away, the broker immediately updates that PC's status to 🔴 Offline so your bot never displays stale data.

💾 Deploying on Target PCs (Two Effortless Methods)

You can easily deploy PC-Remote-Sentinel to any number of target Windows PCs (personal laptops, office desktops, gaming rigs, or brand-new PCs) using either WiFi Network Deployment or a Clean USB Pendrive.

Target PCs only receive the lightweight agent runtime (~250 KB). Master bot code (bot.py), configurations, and credentials are never deployed to target machines.

🌐 Method 1: Over-the-Air Network Deployment (Recommended for 1–100+ PCs)

Deploy to any PC on your local Wi-Fi or LAN without touching a USB drive:

1. On your Main PC, double-click deploy_network.bat (Run as Administrator).
2. It launches the local deployment server and copies the install command to your clipboard.
3. On any target PC on the same Wi-Fi:
   • Press Win + R (Windows Run prompt).
   • Paste the one-liner command:

     powershell -ep bypass -c "irm http://<YOUR_IP>:9090/install | iex"

   • Press Enter and walk away!
4. The target PC automatically elevates, installs the agent in C:\PCSentinel, sets up silent autostart on logon, and immediately connects to your Telegram Bot.

🔌 Method 2: Clean USB Pendrive Setup (~250 KB)

If target PCs are on different networks or have no internet during initial setup:

1. Insert your USB pendrive into your main computer.
2. Double-click prepare_usb.bat and enter your USB drive letter (e.g. E:).
3. The script copies ONLY the necessary agent files (~250 KB) to the USB drive. It leaves behind all bot files, tests, and master secrets. You can also optionally include the offline python-installer.exe for PCs without internet.
4. Plug the USB into the target PC and double-click install.bat.
5. Once complete, unplug the USB drive. The agent is now running silently in the background!

---

🕹️ Telegram Commands Reference

Command	Description
/start, /pcs	Open Fleet Command Center & switch between monitored PCs
/status	View CPU, RAM, Disk, Battery, Uptime, and Active Window
/shot, /screenshot	Capture high-resolution multi-monitor screenshot
/cast, /stream	Start global 30 FPS Live Screen Streaming
/desktop	Desktops & Windows switcher menu (Alt+Tab, Virtual Desktops)
/windows, /apps	List open application windows with 1-tap focus buttons
/switch <name>	Instantly bring matching application window to the front
/webcam	Capture photo from connected webcam
/record_webcam [s]	Record 10s or custom webcam video clip
/record_screen [s]	Record 10s–120s of on-screen desktop video
/lock	Instantly lock the Windows workstation
/top	Display top RAM & CPU consuming processes
/kill <name_or_pid>	Terminate running process (e.g. /kill notepad.exe)
/say <text>	Speak text aloud on PC speakers
/clip <text>	Copy text from phone to PC clipboard
/getclip	Read text from PC clipboard
/get [path]	Open Remote File Explorer, browse directories, or download file
/files, /browse, /explore	Launch interactive Remote File Explorer menu
/alarm [time] [label]	Set countdown timer (10m, 45s, 1.5h) or clock alarm (18:30)
/stopalarm, /silence	Silence and stop ringing PC alarm
/cancelalarm	Cancel pending scheduled alarm countdown
/monitor [on|off]	Turn PC monitors on/off or wake screens
/clean	Audit and clean cached recordings/downloads
/net, /ping, /network	Run network connectivity diagnostics (Telegram API latency ms, Cloud Relay broker, PC reachability)
/open <url>	Open website or app on PC
/cmd <command>	Execute terminal command with token masking
/login <pin>	Authenticate PIN to unlock Command Center
/logout	Lock bot session immediately
/setpin <pin>	Configure or change bot security PIN (4–8 digits)
/removepin	Disable PIN protection completely
/rename [name]	Rename a PC with a friendly custom label
/removepc <name>	Remove an uninstalled PC from the fleet list
/reload	Reload registered fleet registry

---

🧪 Test Suite & Quality Assurance

PC Remote Sentinel includes a comprehensive automated test suite verifying network resilience, retry mechanisms, encryption, and local routing:

# Run the complete test suite
python -m pytest tests/ -v

The test suite covers:

• Telegram Resilience: Safe API execution, exponential backoff retries on network drops, and error handling.
• Agent Media Optimization: Automatic JPEG compression, retry cycles on direct Telegram uploads, and failure reporting.
• Fleet Relay Hardening: Automatic wait-on-reconnect, command timeout retry over QoS 1, and offline PC staleness detection.
• Zero-Latency Routing: Host PC local loopback bypassing external networks.
• Process Isolation & Non-Interference: Strict safeguards preventing accidental termination of trading bots, other Python scripts, OS core services, or Sentinel itself, plus path traversal checks.
• AES-256-GCM Cryptography: Secure payload encryption, decryption, authentication, and nonce freshness.

---

🧹 Clean Uninstallation (Zero Trace)

Removing Sentinel from any PC is just as simple as installing it:

From Monitored Target PCs:

1. Plug your USB pendrive into the target PC and double-click uninstall.bat.
2. Click "Yes" on the Windows UAC elevation prompt.
3. The script terminates all running agent processes, deletes the Task Scheduler task, removes startup hooks, deletes firewall rules, and wipes C:\PCSentinel completely.
4. In Telegram, the PC will show as 🔴 Offline. Simply tap "🗑️ Remove PC from Fleet" (or send /removepc <name>) to clear it from your menu.

From Your Main Host PC:

• Double-click remove_autostart.bat to cleanly remove the startup task and background process.

---

🔒 Security Policy

For security guidelines, vulnerability disclosure, and details on encryption protocols, please refer to SECURITY.md.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.