🛡️ 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.

---

🏗️ 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.
• 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 Files & Clipboard

• File Downloader (/get <path>): Fetch any file from the PC directly into Telegram (up to 50MB).
• 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.

🔒 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.
• 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 (USB Pendrive Setup)

To monitor any PC (personal laptop, gaming PC, home workstation, office desktop, or brand-new unboxed PC):

1. Copy the repository folder to your USB pendrive (ensure install.bat, python-installer.exe, and deploy_config.env are present).
2. Plug the USB pendrive into the target PC.
3. Double-click install.bat.
   • Grants Windows UAC Administrator rights.
   • Automatically installs Python (using the bundled offline installer if not already installed).
   • Copies files to C:\PCSentinel.
   • Registers a silent Task Scheduler auto-start on Windows user logon.
   • Launches the background agent immediately.
4. Unplug your USB drive. The PC is now live in your Telegram bot!

---

🕹️ 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>	Download file from PC to Telegram chat
/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
/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

---

🧹 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.