================================================================================ LURK OS v1.0 — Where Your Stream Comes Alive Vendor: VGC Media Last updated: 2026-05 ================================================================================ This file is a complete, plain-text overview of what Lurk OS is, what it does with and without AI, what hardware it supports, and how it differs from the products you may already know. Open it in Notepad, Notepad++, VS Code, or any text viewer — there is no markdown to render. If you just want to install it: see INSTALL.md. If you just want to launch it: double-click LAUNCH.bat after install.bat. If you want to know what you're getting: keep reading. ================================================================================ TABLE OF CONTENTS ================================================================================ 1. What Lurk OS is (60-second pitch) 2. What's in the box (every panel, one line each) 3. What it does WITH AI 4. What it does WITHOUT AI (offline / Ollama not running) 5. Architecture (single PC vs two-PC setup) 6. Hardware support (NVIDIA / AMD / Intel / none) 7. Integrations (Rumble, OBS, Ollama, Piper, Streamer.bot, etc.) 8. How Lurk OS compares to similar products 9. Privacy + license 10. Support ================================================================================ 1. WHAT LURK OS IS (60-second pitch) ================================================================================ Lurk OS is a Windows desktop application for Rumble livestreamers. It pairs a local-first AI co-host named GLITCH (powered by Ollama on your own PC) with a full engagement toolkit: chat reader, custom commands, timed messages, a viewer economy with games, an event-driven soundboard, sponsor/affiliate rotation, and an AI-generated mini-podcast generator for stream breaks (BRB Studio). Everything that needs to stay private — your chat history, your viewer profiles, your AI conversations, your embeddings — lives in a single folder on your PC called shared_data/. Nothing about your stream is sent to a third-party cloud you don't control. Internet is used only for the few things that genuinely need it (Google Cloud Speech for mic input, Rumble's chat API, DuckDuckGo and NOAA for the BRB news/weather feed, and a one-time license-key verification on first launch). Lurk OS is opt-in two-PC. On a single beefy PC, run it end-to-end. On a streaming rig + AI rig, run PC1 as "the brain" (Ollama, bot server, shared data) and PC2 as "the station" (a thin UI that proxies everything back to PC1). The split is a config switch, not a separate install. ================================================================================ 2. WHAT'S IN THE BOX (every panel, one line each) ================================================================================ Dashboard — Real-time snapshot: followers, last chat, command rate, upcoming giveaway, mini soundboard, system health. Glitch Chat — Multi-project AI chat with semantic memory search. Bot Monitor — Live event log: commands, subs, raids, donations, first-chat moments, and command/min rate. Viewers & Roster — Registered viewer profiles: mods, VIPs, regulars. Badges, notes, follower-status tags. Bot Studio — Personality editor, command builder, timed-message scheduler, affiliate rotation manager. Commands — Built-in games + custom commands + SFX shop. BRB Studio — AI mini-podcast generator (script + narration) for stream breaks. Pulls live news + space weather. Soundboard — Audio clip library with manual pads, event triggers (raid/follow/sub/donation/first_chat) and keyword bindings; plays through OBS or local audio. Creator Tools — Stream-description generator + X/Discord post helpers. Stream Control — OBS scene/source control, session archiving, follower + giveaway counters. Settings — Per-PC role, Rumble/OBS/Ollama config, AI model picker, microphone device, voice picks, feature toggles (TTS, chat reader, PTT, OBS, BRB, etc.). Status — System health dashboard. PC1 and PC2 side-by-side cards (CPU%, RAM, disk, GPU%, VRAM, GPU temp). AI Models card with GPU/CPU split sliders. ================================================================================ 3. WHAT IT DOES *WITH* AI ================================================================================ GLITCH chat — three personality modes: Vlad mode (private / mic / streamer-only context) Conversational with the streamer. Has access to full memory, viewer summaries, and affiliate context. Answers can be long. Viewer mode (live Rumble chat replies to !ai / !glitch ) Short, punchy replies (~200 chars). Knows the asker's history (returning viewer? mod? donor?) and adjusts tone accordingly. Wake mode (just the bot's name, no question) Free-form status update or roast. Used when chat types "@glitch" without asking anything. Semantic memory: Every chat message becomes a vector embedding (default model: nomic-embed-text via Ollama). Past conversations are searchable. When GLITCH replies, it pulls in the most relevant prior context, so it doesn't forget who you and your regulars are between streams. BRB Studio: Generates a fresh mini-podcast every stream break. Two AI voices (narrator + guest character). Pulls live data: space weather from NOAA, gaming news via DuckDuckGo. Plays through OBS or local speakers. Voice in / Voice out: - Mic STT via Google Cloud Speech, wake-word: say the bot's name to talk to GLITCH. Push-to-talk on Mouse Button 5 also routes to STT. - TTS via Piper (offline neural voices, four bundled: Bryce, Joe, John, Kathleen) or Windows SAPI fallback. Per-lane volume + master volume. Affiliate-aware prompt augmentation: The "pushiness" knob (very_subtle / subtle / decent / pushy / very_pushy) decides how aggressively the AI weaves your sponsor/affiliate mentions into !ai replies. Off if you want a clean chat. Agentic tool calls: Up to 30 messages of history are passed to the model each call. The AI can ask for follow-ups itself (the "agent loop") — useful for multi-step answers like "look up X then summarize." ================================================================================ 4. WHAT IT DOES *WITHOUT* AI (offline / Ollama not running) ================================================================================ Lurk OS does not become a doorstop when Ollama is down. Every non-AI panel still works: Soundboard Manual click-to-play pads, event-triggered clips (raid/follow/sub/ donation/first_chat), keyword bindings ("if chat contains X, play Y"), per-clip cooldowns, global cooldown, master volume. Route per clip: local winsound or OBS media source. Viewer economy (VGC_BOT subsystem) Dual currency: Stash Credits (low tier) + Cartel Coins (high tier). Commands: !points, !top, !shop, !duel, !heist, !roll, !gift, !convert, !loot, !stash, !boss, !unlurk. Configurable drop rates, cooldowns, role gates. Expandable gear database for loadouts. Custom commands User-defined !whatever with cooldowns and role gates (anyone / regular / mod / streamer). Random response picker. Timed messages Auto-posts on a fixed interval. Skip-if-chat-dead threshold so the bot doesn't talk to an empty room. Affiliates can ride in the rotation. Affiliate / sponsor rotation Managed URL list with discount codes and short blurbs. Used by the timed-message rotation and the AI prompt; the rotation itself does NOT need AI. Audio mixer Master + 6 lanes (chat TTS, GLITCH reply, bot, BRB narrator, BRB assistant, legacy pyttsx3). Per-lane mute/volume saved per PC. Stream session archiving Each stream gets auto-saved as a Project containing one searchable Chat ("[HH:MM:SS] username: text"). Persists on stream end. Searchable across past streams. OBS WebSocket control Scene switching, source toggling, BRB playback. Configured in Settings; can run on PC1 or PC2. Push-to-talk Mouse Button 5 → mic capture → STT → routes to AI (PC1) or remote PC1 from PC2. Rumble chat I/O Read: SSE (Server-Sent Events) direct from Rumble's chat backend. Real-time, no polling, no Chrome extension needed. Send: Rumble's internal chat API using YOUR own logged-in session cookie (password encrypted on disk via Windows DPAPI). No Chrome extension. No third-party relay required. The bot's identity is your account. If Ollama isn't reachable on launch, the Status bar shows a red "AI: offline" pill that clicks through to the Status page where you can repair the daemon. ================================================================================ 5. ARCHITECTURE ================================================================================ Two roles, one codebase: PC1 ("The Brain") - Runs Ollama (local LLM at localhost:11434). - Runs bot_server on port 5051 (Flask) so PC2 can read/write data. - Owns shared_data/ — the single source of truth. - Runs the chat reader (SSE) + chat sender (Rumble session cookie). - Can also run the UI (single-PC mode). PC2 ("The Station") - Lightweight UI. Same app.py, but role=pc2 in local_config.json. - Every panel proxies through HTTP to PC1's bot_server. There is no "local edits drift away from PC1" — edits on PC2 land at PC1. - Runs a tiny audio receiver on port 7778 so PC1's TTS can be played out PC2's speakers (the actual streaming PC). - Optional: PC2 may also run OBS (it's the encoder), but that's orthogonal — OBS can live anywhere. Persistence layout: shared_data/ (preserved across updates) channel_config.json bot personality, currencies, channel info stream_config.json Rumble API, follower count, giveaway, OBS custom_commands.json timed_messages.json affiliates.json soundboard_config.json + soundboard/ chats/ per-chat history (one JSON per chat) projects/ chat groupings (typically per-stream) special_users.json mods / regulars / VIPs roster viewers.json summaries for fast lookup bot_data/ VGC_BOT: points, stats, gear, logs memory_index.jsonl semantic embeddings index local_config.json per-machine: role, PC1 URL, mic device, audio lanes, UI scale (1.0x / 1.25x / …) ================================================================================ 6. HARDWARE SUPPORT ================================================================================ Lurk OS auto-detects your GPU at install time (install.bat → setup/hardware.py) and pip-installs only the matching monitoring library. The Status page reflects the result. NVIDIA Full Ollama GPU offload (Ollama uses CUDA on Windows). Live monitoring via pynvml: GPU utilization, VRAM used/total, temperature. AMD Ollama runs on CPU on Windows. (Ollama doesn't ship a ROCm build for Windows yet; CUDA-only on this platform.) Live monitoring via pyadl: utilization + temperature. VRAM total via WMI. (Used VRAM isn't reliably exposed by ADL on Windows, so that cell shows "—".) Intel Iris / Arc iGPUs and dGPUs work for the UI. AI runs on CPU. GPU name is shown in Status; live util/VRAM/temp not available (no stable Python SDK for Intel GPU stats on Windows). No GPU CPU-only AI. Everything else works exactly the same. Minimum requirements: - Windows 10 or 11. - Python 3.10–3.12 (installer ships 3.12.10 if you don't already have a compatible Python). - 8 GB RAM (16 GB recommended for the 3B Ollama model). - 10 GB free disk for the install + a small Ollama model. More models = more space. - Internet for STT, BRB news/weather, and license verification. If install.bat misdetects your hardware (or you swap GPUs later), open the setup wizard again and click "Retry hardware install" on the Hardware step. ================================================================================ 7. INTEGRATIONS ================================================================================ Rumble Read: SSE direct to Rumble's chat backend. Real-time, no polling, no extension. Send: Rumble's internal chat API via YOUR logged-in session cookie. Password is DPAPI-encrypted on disk. No Chrome extension or third party. Polling fallback (rumble_poller) is also available if SSE is ever blocked. OBS Studio 28+ WebSocket 5 (default port 4455). Scene switching, source toggling, media playback for BRB clips. Ollama Local LLM inference, HTTP REST at localhost:11434. Auto-starts on app launch if not already running. Default model: llama3.2:3b (configurable). Piper TTS Local neural voices. Four bundled (Bryce, Joe, John, Kathleen). GPL-3.0; opt-in install via INSTALL_PIPER.bat. Without Piper, Windows SAPI (pyttsx3) is the fallback. Google Cloud STT Speech-to-text for wake-word and PTT. Requires internet. Free tier covers casual streaming usage; not metered by Lurk OS itself. NOAA APIs Space weather data for BRB Studio podcasts. Public, no auth. DuckDuckGo Gaming news lookups for BRB Studio. No API key. Streamer.bot Optional WebSocket relay (in VGC_BOT). If you already use Streamer.bot for visual automation, Lurk OS can hand off messages to it. You can run both side-by-side: Lurk OS for AI + economy + BRB, Streamer.bot for node-graph automation. ================================================================================ 8. HOW LURK OS COMPARES ================================================================================ These are honest comparisons, not marketing. Lurk OS is good at some things and explicitly not trying to be others. If a product on this list is the right tool for your job, use it. -------------------------------------------------------------------------------- vs Rumble's built-in bot -------------------------------------------------------------------------------- Rumble bot: Server-side. Timers, simple !commands, basic auto-mod. No AI. No memory of past viewers. Read-only from your side — you can't extend it. Lurk OS: Everything Rumble's bot does, plus: - Local AI co-host with semantic memory - Per-viewer profile (mod / regular / VIP / first-chat) - Soundboard with event triggers - Dual-currency viewer economy with games - Affiliate rotation - BRB AI mini-podcast generator - TTS + STT pipelines Reads chat via SSE direct from Rumble (real-time). Sends through YOUR logged-in account, so replies look like the streamer — not a third-party bot agent that viewers have to trust separately. -------------------------------------------------------------------------------- vs Streamer.bot -------------------------------------------------------------------------------- Streamer.bot: Visual node-editor automation. Heavy on Twitch hooks (Twitch is its native platform). Excellent for complex if-this-then-that flows. No bundled AI. No semantic memory. No TTS-with-memory. Lurk OS: Rumble-first. AI is a first-class citizen, not a plugin you have to wire up. Less flexible than Streamer.bot's node graph; more out-of-the-box for streaming + AI. Lurk OS BRIDGES to Streamer.bot via the bundled WebSocket relay (VGC_BOT/streamerbot_relay.py) if you want both: Lurk OS for AI/BRB/economy, Streamer.bot for visual automation. -------------------------------------------------------------------------------- vs Streamlabs (Desktop / Cloudbot) -------------------------------------------------------------------------------- Streamlabs: Cloud-hosted bot + an OBS-derived encoder UI. Twitch + YouTube focused. Closed source. Subscriptions for advanced features. Your chat data lives on their servers. Lurk OS: Fully local. No subscription. No cloud dependency for AI or chat storage. Your chat data stays in shared_data/chats/ on YOUR machine. No streaming encoder built in — you bring OBS. (We think encoding is OBS's job, not the bot's.) -------------------------------------------------------------------------------- vs Mix It Up Bot -------------------------------------------------------------------------------- Mix It Up: Free, open-source bot. Strong command/games support. Twitch / YouTube / Trovo native — not Rumble. No AI. No semantic memory. Lurk OS: Similar command + games surface (we ship a 12-command built-in suite plus a dual-currency economy with duels, heists, rolls, gifts, gear), AND adds: - Local AI co-host with semantic memory - BRB AI mini-podcast generator - Voice in (STT) + voice out (Piper TTS) - Affiliate-aware AI prompts Rumble is our native platform; we read chat via SSE directly. Mix It Up doesn't currently support Rumble. -------------------------------------------------------------------------------- vs OBS Studio + plugins (the DIY baseline) -------------------------------------------------------------------------------- DIY: OBS Studio + advanced-scene-switcher + browser-source overlays + custom Lua/Python scripts + a separate chat bot tool + a separate sound-effect tool + a separate alert tool. Maximum flexibility, maximum maintenance. Lurk OS: Replaces the "plus" — the 10+ plugins, the bot, the AI overlay, the chat reader, the soundboard, the BRB system — with one Python program you can read. OBS still does the streaming; Lurk OS does the brain. If you love wiring plugins together, the DIY route stays flexible. If you want it to work end-to-end out of the box, this is the tradeoff. ================================================================================ 9. PRIVACY + LICENSE ================================================================================ Local-first by default. What stays on your PC: - All chat history (shared_data/chats/) - All AI conversations and embeddings (shared_data/memory_index.jsonl) - Viewer profiles, points, gear, command logs (shared_data/bot_data/) - Soundboard clips and config (shared_data/soundboard/) - Bot personality, channel config, currencies (channel_config.json) - Your Rumble password (DPAPI-encrypted in stream_config.json so another Windows user can't decrypt it from a copy of the file) What touches the internet, and only when called: - Google Cloud Speech — sent the audio of your wake-word and follow-up when you talk to GLITCH. Not stored by Lurk OS. - Rumble chat backend — to read live chat (SSE) and post replies (chat API). - DuckDuckGo + NOAA — only when BRB Studio is generating a podcast. - License verification — one-time, on first launch. You can see exactly when the network is touched by watching the daily log at logs/lurk_os_.log. License: Per-user personal license. Non-transferable. See LICENSE.txt for full terms. Bundled third-party software (Piper, customtkinter, requests, flask, etc.) is licensed under their own terms — see THIRD_PARTY_LICENSES.txt for the full list and SPDX identifiers. ================================================================================ 10. SUPPORT ================================================================================ Support, feature requests, bug reports: contact VGC Media via the channel where you bought your license. Critical bugs that block a stream get priority; cosmetic gripes get a fix in the next update. Before reporting a bug, please: - Look at logs/lurk_os_.log for the actual error. - Try Settings → System → Run Preflight Checks. - Try Status → AI Models → Repair if the AI is offline. If you're going to ship Lurk OS to another PC (e.g. PC2 in a two-PC setup), copy the full install folder plus shared_data/, then run install.bat on the new machine. The vendor-aware installer will detect the new GPU and install the right monitoring SDK automatically. ================================================================================ End of ABOUT_LURK_OS.txt ================================================================================