teledesk 1.0.0

Control your entire laptop from Telegram — screenshots, shell, files, processes, power, and more.

🖥️ TeleDesk

Control your entire laptop from Telegram. Screenshots, shell commands, file management, process control, power management, mouse & keyboard — all from a Telegram chat.

---

⚡ Quickstart

pip install teledesk
teledesk setup
teledesk start

That's it. Open Telegram, message your bot /start, and you're in control.

---

📦 Installation

# Basic install
pip install teledesk

# With all optional features (screenshot, clipboard)
pip install teledesk[full]

Python 3.9+ required. Works on macOS, Linux, and Windows.

---

🚀 Setup Wizard

TeleDesk has an interactive setup wizard that walks you through everything:

$ teledesk setup

 ████████╗███████╗██╗     ███████╗██████╗ ███████╗███████╗██╗  ██╗
 ╚══██╔══╝██╔════╝██║     ██╔════╝██╔══██╗██╔════╝██╔════╝██║ ██╔╝
    ██║   █████╗  ██║     █████╗  ██║  ██║█████╗  ███████╗█████╔╝
    ██║   ██╔══╝  ██║     ██╔══╝  ██║  ██║██╔══╝  ╚════██║██╔═██╗
    ██║   ███████╗███████╗███████╗██████╔╝███████╗███████║██║  ██╗
    ╚═╝   ╚══════╝╚══════╝╚══════╝╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝

    Control your laptop. Entirely from Telegram.

┌─ Welcome to TeleDesk Setup ─────────────────────────────────┐
│ This wizard will configure your bot in under 2 minutes.     │
└─────────────────────────────────────────────────────────────┘

Step 1/4 — Bot Token
...

The wizard handles:

• Bot token entry & live validation (tests connection to Telegram)
• Authorized user ID collection
• Download/upload directory configuration
• Screenshot quality settings
• Optional dependency check

---

🤖 All Commands

🖥️ System

Command	Description
/info	Full system overview (OS, CPU, RAM, disk, battery)
/cpu	Per-core CPU usage with visual bar chart
/mem	RAM & swap with bar chart
/disk	All drives with usage bars & live I/O speeds
/battery	Charge level, status, time remaining
/network	All interfaces, IPs, live throughput
/uptime	System uptime & boot time
/top	Live updating resource monitor (5 refreshes)

⚙️ Processes

Command	Description
/ps [name]	Top processes by CPU, optional filter
/kill <pid> [signal]	Kill/suspend/resume a process

💻 Shell

Command	Description
/run <cmd>	Run any shell command, stream output
/sh <cmd>	Alias for /run
/runbg <cmd>	Run in background, notify when done
/pipe cmd1 ||| cmd2	Build shell pipelines
/env	View environment variables
/which <prog>	Find program + version
/cron <secs> <cmd>	Schedule repeating command
/cronjobs	List active scheduled jobs
/cronstop <id>	Stop a scheduled job

📂 Files

Command	Description
/ls [-a] [-s] [path]	List directory (hidden, sort by size)
/cd <path>	Change directory
/pwd	Show current directory
/cat <file>	Read file (auto syntax highlight, auto-send large files)
/stat <path>	File/directory metadata
/find <pattern> [in dir]	Find files by name
/grep <pattern> [path]	Search text in files
/mkdir <name>	Create directory
/rm [-r] <path>	Delete (with confirmation)
/mv <src> <dst>	Move/rename
/cp <src> <dst>	Copy
/write <file> <content>	Write text to file
/download <path>	Send file to Telegram (auto-zips directories)
/upload	Receive file from Telegram
/zip <path>	Create zip archive
/unzip <file.zip>	Extract zip

📸 Screen & Input

Command	Description
/screenshot [delay]	Take screenshot (with optional delay)
/ss	Quick screenshot alias
/type <text>	Type text using keyboard automation
/key <shortcut>	Press keyboard shortcuts (ctrl+c, cmd+space, etc.)
/click <x> <y> [btn] [n]	Mouse click (left/right/middle, single/double)
/scroll <amount>	Scroll mouse wheel
/move <x> <y>	Move mouse cursor
/mousepos	Get current mouse position + screen size
/open <app|file|url>	Open application, file, or URL

📋 Clipboard

Command	Description
/copy <text>	Copy text to clipboard
/paste	Read clipboard contents

🔔 UI & Media

Command	Description
/notify <title> | <msg>	Desktop notification
/volume [0-100|up|down|mute]	Get or set volume
/brightness <0-100>	Set screen brightness

🔋 Power

Command	Description
/shutdown	Shutdown (with confirmation)
/restart	Restart (with confirmation)
/sleep	Sleep / suspend
/hibernate	Hibernate
/lock	Lock screen
/logout	Log out current user
/screensaver	Activate screensaver
/displays	List connected displays

⚙️ Bot Management

Command	Description
/config	View or change settings
/logs	Audit log of all commands
/status	Quick bot status

---

🖥️ CLI Commands

teledesk setup       # Interactive onboarding wizard
teledesk start       # Start the bot
teledesk start -v    # Start with verbose logging
teledesk status      # Check configuration & dependencies
teledesk config      # View/edit settings interactively
teledesk logs        # View command audit log
teledesk test        # Test Telegram API connection
teledesk adduser     # Add an authorized Telegram user
teledesk stop        # Stop running bot (if backgrounded)
teledesk uninstall   # Remove all TeleDesk data

---

🔒 Security

TeleDesk is built with security as a priority:

• User whitelist — Only Telegram user IDs you add in ALLOWED_IDS can control the bot
• Silent rejection — Unauthorized users get no response (no feedback to attackers)
• Secure config — Config stored in ~/.teledesk/config.env with chmod 600
• Audit logging — Every command is logged with timestamp, user, and arguments
• Confirmation dialogs — Destructive actions (shutdown, delete) require inline confirmation
• Token protection — Token is never logged or displayed in full

Add multiple authorized users:

teledesk adduser   # Interactive
# or:
# Edit ~/.teledesk/config.env:
# TELEDESK_ALLOWED_IDS="111222333,444555666"

---

⚡ Run at Startup

macOS (launchd)

<!-- ~/Library/LaunchAgents/com.teledesk.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>             <string>com.teledesk</string>
    <key>ProgramArguments</key>  <array><string>/usr/local/bin/teledesk</string><string>start</string><string>--no-banner</string></array>
    <key>RunAtLoad</key>         <true/>
    <key>KeepAlive</key>         <true/>
    <key>StandardErrorPath</key> <string>/tmp/teledesk.err</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.teledesk.plist

Linux (systemd)

# /etc/systemd/system/teledesk.service
[Unit]
Description=TeleDesk Laptop Control Bot
After=network.target

[Service]
Type=simple
User=youruser
ExecStart=/usr/local/bin/teledesk start --no-banner
Restart=always
RestartSec=10
Environment=DISPLAY=:0

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now teledesk

Windows (Task Scheduler)

$action  = New-ScheduledTaskAction -Execute "teledesk" -Argument "start --no-banner"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "TeleDesk" -Action $action -Trigger $trigger -RunLevel Highest

---

🔧 Configuration

Config is stored at ~/.teledesk/config.env:

TELEDESK_BOT_TOKEN=1234567890:ABCdef...
TELEDESK_ALLOWED_IDS=123456789,987654321
TELEDESK_DOWNLOAD_DIR=/Users/you/Downloads
TELEDESK_UPLOAD_DIR=/Users/you/Desktop
TELEDESK_MAX_FILE_MB=50
TELEDESK_SCREENSHOT_QUALITY=85
TELEDESK_LOG_COMMANDS=true

Change settings interactively: teledesk config
Or inside Telegram: /config set max_file_mb 100

---

📦 Optional Dependencies

Package	Feature
pyautogui	Screenshot, type, click, scroll, mouse
Pillow	Screenshot compression
pyperclip	Clipboard read/write
aiofiles	Fast async file operations

pip install pyautogui Pillow pyperclip aiofiles

---

🛠️ API Usage

Use TeleDesk as a library:

from teledesk import Config, TeleDeskBot

config = Config()
# config is auto-loaded from ~/.teledesk/config.env

bot = TeleDeskBot(config)
bot.run()

---

📄 License

MIT — See LICENSE