OwlBot is a production‑ready modular remote‑control agent for Windows, operated via Telegram. It lets you monitor system resources, manage files, control peripherals, capture screen / webcam, and more — all from your phone.
- 🧩 100% Modular — load only the modules you need
- 💉 Dependency‑Injected core — ready for extra platforms (Discord, SSH, …)
- 🛡️ User‑ID whitelisting and centralized error handling
- 📊 Live resource monitoring (CPU, RAM, Disk, temperature)
- 🎹 Peripheral control — keyboard, mouse, hotkeys, audio volume
- 📸 Screen capture, webcam, timelapse, and screen streaming
- 🔊 Voice recording, volume control, and incoming‑voice playback
- 🌍 IP lookup, VPN/proxy detection, and GPS/IP-based location (Telegram map pin)
- Python 3.11+
- Windows (some modules require Win32 API)
ffmpeginPATHif you use voice playback (download from ffmpeg.org)- A Telegram Bot Token
pip install owlbot-remote[all]To install only the cross‑platform subset (no audio, no keyboard, no WMI):
pip install owlbot-remotefrom owlbot import OwlBot
bot = OwlBot(
token="YOUR_BOT_TOKEN",
authorized_users=[123456789], # your Telegram user ID
modules=["system", "screen", "files", "input", "processes", "monitoring"],
)
bot.run()Or via the CLI entry point:
owlbot --token YOUR_BOT_TOKEN --users 123456789,987654321By default OwlBot logs to both the console and a rotating‑free log file
(owlbot.log in the current directory). All of this is configurable:
from owlbot import OwlBot
bot = OwlBot(
token="YOUR_BOT_TOKEN",
authorized_users=[123456789],
log_level="DEBUG", # DEBUG | INFO | WARNING | ERROR | CRITICAL
log_file="owlbot.log", # set to None (or "") to disable the log file only
enable_logging=True, # set to False to disable logging entirely
)| Goal | Setting |
|---|---|
| Console + file logging (default) | leave as default |
| Console only, no log file on disk | log_file=None |
| Completely silent (no console, no file) | enable_logging=False |
The same options are available from the CLI:
owlbot --token TOKEN --users 123 --log-level DEBUG # verbose logging
owlbot --token TOKEN --users 123 --no-log-file # console only, no file
owlbot --token TOKEN --users 123 --disable-logging # fully silent| Module | Command | Description |
|---|---|---|
| system | /status |
CPU, RAM, Disk, Network, Battery |
/uptime |
System uptime | |
/ping |
Health‑check | |
/lock |
Lock workstation | |
/shutdown |
Shut down PC | |
/restart |
Reboot PC | |
| screen | /screenshot |
Capture desktop |
/webcam |
Capture webcam photo | |
/timelapse <s> <n> |
Series of screenshots | |
/startstream |
Start screen streaming | |
/stopstream |
Stop & send video | |
| input | /type <text> |
Type text |
/move <x> <y> |
Move mouse | |
/mousepos |
Get mouse position | |
/mouse <action> |
Click / scroll / drag | |
/hotkey <k1+k2> |
Send hotkey | |
/msg <text> |
Show message box | |
| audio | /mute / /unmute |
Toggle mute |
/volume <0‑100> |
Set volume | |
/startrec [sec] |
Record microphone | |
/stoprec |
Stop & send recording | |
/playvoice |
Toggle incoming‑voice playback | |
| files | /listdir [path] |
List directory |
/getfile <path> |
Download file | |
/hide / /show |
Toggle hidden attribute | |
/file copy/move/delete |
File operations | |
| processes | /tasklist |
List running processes |
/killtask <exe> |
Kill a process | |
/run / /cmd / /script |
Execute commands | |
| monitoring | /monitor <cpu|ram|disk|temp> |
Periodic alerts |
/stopmonitor |
Stop alerts | |
| network | /netcheck |
Check internet connection |
/wifiscan |
Scan Wi‑Fi networks | |
/clipboard get|set |
Read / write clipboard | |
| ffmpeg | /ffmpeg |
Check FFmpeg status |
/ffmpeg_install |
Download & install FFmpeg | |
| ip | /myip |
Public + local IP addresses |
/iplookup [ip] |
Geo/ISP lookup (self or given IP) | |
/vpncheck |
Detect VPN/proxy/hosting IP | |
/location |
Send IP-based location pin | |
/gps |
Real GPS fix (Windows), IP fallback | |
/locationlive <sec> |
Live location for N seconds (IP-based) | |
/gpslive <sec> |
Live GPS tracking (Windows), auto-updates in place | |
/stopgpslive |
Stop live GPS tracking early |
owlbot/
├── __init__.py # Package exports & version
├── config/ # BotConfig dataclass
├── core/
│ ├── bot.py # Main OwlBot engine
│ ├── decorators.py # @authorized_only / @safe_reply
│ └── utils.py # Shared helpers
├── modules/
│ ├── base.py # BaseModule interface
│ ├── system.py # System control
│ ├── screen.py # Screen/webcam/stream
│ ├── files.py # File operations
│ ├── processes.py # Process management
│ ├── input.py # Keyboard/mouse (Windows)
│ ├── audio.py # Audio control (Windows)
│ ├── monitoring.py # Resource monitoring
│ ├── network.py # Wi‑Fi / clipboard
│ └── ip.py # IP lookup, VPN check, GPS/IP location
└── platform/
└── telegram.py # Telegram adapter
The test suite uses pytest and makes no real network / Telegram calls.
pip install -e .[dev]
pytest -vLint (matches CI, config lives in .flake8):
flake8 src tests| Extra | Includes |
|---|---|
owlbot-remote[ui] |
pyautogui, opencv‑python, numpy |
owlbot-remote[windows] |
wmi, pycaw, keyboard, pywifi, pyaudio |
owlbot-remote[all] |
Everything above |
owlbot-remote[dev] |
Dev / CI tools (build, flake8, pytest) |
Distributed under the MIT License. See LICENSE for details.
All guides and API references are in the docs/ directory (English only):
| Guide | Description |
|---|---|
| Getting Started | Installation, configuration, quick start |
| Configuration | Complete configuration reference |
| Modules | All modules, commands, and features |
| API Reference | Python API reference |
| Security | Security best practices |
| Development | Contributing, testing, releasing |
| Examples | Usage examples and patterns |
| Documentation Index | Full documentation index |
All technical docs are English-only. README translations are in docs/:
| Language | File |
|---|---|
| 🇮🇷 Persian/Farsi | README-fa.md |
| 🇪🇸 Spanish | README-es.md |
| 🇮🇹 Italian | README-it.md |
| 🇩🇪 German | README-de.md |
| 🇨🇳 Chinese (Simplified) | README-zh.md |
| 🇫🇷 French | README-fr.md |
| 🇷🇺 Russian | README-ru.md |
| 🇯🇵 Japanese | README-ja.md |
| 🇳🇱 Dutch | README-nl.md |
| 🇹🇷 Turkish | README-tr.md |
| 🇰🇷 Korean | README-ko.md |
This library is provided for your own convenience — to remotely manage your own devices that you own or are explicitly authorized to administer. It is not intended for surveillance, monitoring, or control of any device or person without their knowledge and consent.
Any misuse of this library (including unauthorized access to systems you do not own, tracking or monitoring individuals without consent, or any illegal activity) is solely the responsibility of the user. The author and maintainer(s) are not liable for any misuse, damages, or legal consequences arising from the use of this software. Use responsibly and in accordance with the laws of your jurisdiction.
Maintained by Sepehr H.I 🦉