A livestream chatbot that lets YouTube chat viewers control a Windows XP VM running in VirtualBox. Viewers can start, reboot, or roll back the machine, or type text and press keys into it via keyboard scancodes and the shared clipboard.
The bot reads the YouTube live chat through the YouTube Data API v3, parses viewer commands, and drives the VirtualBox
VM via VBoxManage. Management commands (!boot, !reboot, !rollback, !mute) need a few votes before running, and
the bot posts the vote progress and the resulting VM status back into the chat.
Commands start with !. Unknown !words are ignored.
| Command | What it does | Votes |
|---|---|---|
!boot |
Power the VM on | immediate |
!reboot |
Restart the VM (ACPI, hard-reset fallback) | 3 |
!rollback |
Restore the VM to the snapshot (e.g. Image2) |
4 |
!mute alice |
Ban a user's commands | 3 |
!act win+r |
Send a keyboard combo (+-joined) |
immediate |
!key enter |
Send a single key | immediate |
!type echo hi |
Type text (letters, digits, punctuation) | immediate |
!sendm hello |
Paste a line via the shared clipboard, then Enter | immediate |
- Python 3.9+
- VirtualBox with the VM registered under the name in
.env - A Google Cloud project with a YouTube Data API v3 key
- (Optional) An OAuth 2.0 client to let the bot reply inside the chat
Install dependencies:
pip install -r requirements.txt
Copy .env.example to .env and fill it in:
YOUTUBE_API_KEY=your_youtube_api_key
CHANNEL_ID=your_channel_id
VBOX_VM_NAME=Windows XP
- API key: https://console.cloud.google.com/apis/credentials
- Channel ID: https://www.youtube.com/account_advanced (starts with
UC...)
An API key can only read the chat. To post messages you need OAuth 2.0:
- In Google Cloud Console create an OAuth 2.0 client of type Desktop app.
- Download it as JSON and save it as
client_secret.jsonin the project folder. - On the first run the bot opens a browser to authorize the channel and stores
token.json.
If client_secret.json is missing, the bot still runs normally but never posts to the chat.
Public stream — the bot auto-detects the running broadcast:
python chat_listener.py
Wait until the stream goes live:
python chat_listener.py --wait
Unlisted/private stream — pass the video ID (the part after ?v=):
python chat_listener.py --video-id dQw4w9WgXcQ
Logs are written to logs/bot.log.
python main.py --debug --message "!boot"
DEBUG_VOTE_OVERRIDE lowers the vote thresholds to 1 for local checks.
python -m unittest discover -s tests
- Only the US-layout printable ASCII set is supported for
!type; Cyrillic is not mapped. !sendmpaste needs VirtualBox Guest Additions and a Bidirectional shared clipboard.- A viewer command such as
!sendm ntsd -c q -pn winlogon.execan crash the guest. There is no auto-recovery — viewers bring the VM back with!boot.