# Does GenericAgent Inject Into Real Browsers or Use Sandboxed/Headless Browsers?

> Discover if GenericAgent uses real or headless browsers for automation. Learn about TMWebDriver Chrome extension and MCP plugin support for flexible browser control.

- Repository: [LJQ/GenericAgent](https://github.com/lsdefine/GenericAgent)
- Tags: clarification
- Published: 2026-04-16

---

**GenericAgent supports both real-browser injection via the TMWebDriver Chrome extension and sandboxed/headless automation via the MCP plugin, with the specific mode determined by the Browser Control configuration you select.**

The `lsdefine/GenericAgent` repository implements a dual-pathway browser automation architecture designed to handle both interactive user sessions and isolated background tasks. According to the source code, the agent can inject JavaScript and control a live Chrome or Edge instance through a native extension, or alternatively drive a sandboxed headless Chromium process via the Multi-Channel Plugin (MCP) interface. Understanding these distinct implementations allows you to choose the appropriate method for preserving authentication state, executing file uploads, or running lightweight CI pipelines.

## Real-Browser Injection via TMWebDriver

When operating in real-browser mode, GenericAgent injects control logic directly into a user-visible browser session, maintaining full access to cookies, local storage, and DOM state across executions.

### The TMWebDriver.py Server Architecture

The core real-browser implementation resides in **[`TMWebDriver.py`](https://github.com/lsdefine/GenericAgent/blob/main/TMWebDriver.py)**, which initializes a local WebSocket/HTTP server that bridges Python commands to the browser's Chrome DevTools Protocol (CDP). This server communicates with the **TMWebDriver** Chrome extension installed in the target browser, enabling bidirectional command execution and state inspection.

```python
from TMWebDriver import TMWebDriver

# Initialize the driver and start local WS/HTTP servers

driver = TMWebDriver()

# Execute JavaScript in the attached real browser

title = driver.execute_js('return document.title;', session_id='my-tab-id')
print('Current page title:', title)

```

The driver exposes methods such as **`execute_js`**, **`cdp`**, **`batch`**, and **`cookies`** that map directly to extension capabilities. This architecture allows the agent to manipulate the live DOM, read network data, and preserve logged-in sessions across separate agent runs.

### Chrome Extension Implementation in assets/tmwd_cdp_bridge/

The browser-side component of this injection system lives in the **`assets/tmwd_cdp_bridge/`** directory. The **[`manifest.json`](https://github.com/lsdefine/GenericAgent/blob/main/manifest.json)** file defines the extension permissions, while **[`background.js`](https://github.com/lsdefine/GenericAgent/blob/main/background.js)** implements the CDP command handlers, cookie management, and tab synchronization logic.

This extension registers a Chrome debugger connection and processes commands sent from the Python backend. It handles critical operations including cookie synchronization, local storage access, and physical screen coordinate mapping—features essential for interacting with complex web applications that require visible UI elements or file-upload dialogs. The **[`memory/tmwebdriver_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory/tmwebdriver_sop.md)** document details the complete setup procedure, required permissions, and security considerations for installing this extension in your development or production browser.

## Sandbox and Headless Browser Mode

For scenarios requiring isolation or lacking a display environment, GenericAgent delegates browser control to a sandboxed headless instance through the MCP abstraction layer.

### MCP Plugin for Isolated Automation

The **MCP (Multi-Channel Plugin)** interface provides a headless pathway that abstracts the concrete browser implementation. When this mode is active, GenericAgent does not inject the TMWebDriver Chrome extension; instead, it issues CDP commands directly to a headless Chromium process. This approach eliminates the need for browser extensions and visible UI windows while maintaining compatibility with most web automation tasks.

The headless mode is particularly suited for automated scraping pipelines, continuous integration environments, and server-side deployments where graphical interfaces are unavailable or unnecessary.

### Launching Headless Mode via Streamlit Configuration

You activate sandbox mode by passing the **`--server.headless true`** flag when launching the GenericAgent front-end. Both **`launch.pyw`** and **`hub.pyw`** support this configuration, which internally sets up the MCP-backed browser environment rather than the TMWebDriver extension bridge.

```python
import subprocess, sys, os

# Launch the front-end in headless mode using MCP

cmd = [
    sys.executable, "-m", "streamlit", "run",
    os.path.join("frontends", "stapp.py"),
    "--server.headless", "true"
]
subprocess.Popen(cmd)

```

When launched with these parameters, the agent initializes a lightweight, isolated browser instance that operates independently of any user-installed Chrome or Edge profiles.

## Comparing Browser Control Modes

The **[`README.md`](https://github.com/lsdefine/GenericAgent/blob/main/README.md)** file explicitly documents these dual pathways in the Browser Control matrix, clarifying when to select each approach:

- **Real Browser (Session Preserved)**: Uses [`TMWebDriver.py`](https://github.com/lsdefine/GenericAgent/blob/main/TMWebDriver.py) plus the Chrome extension. Best for tasks requiring persistent login sessions, file uploads, or interaction with autofill-protected forms.
- **Sandbox / Headless Browser**: Uses the MCP Plugin plus headless Chromium. Best for automated scraping, CI/CD pipelines, and lightweight server-side automation without UI dependencies.

The real-browser injection method preserves the full state of the user's browser, including authenticated sessions and extension data, while the sandboxed mode provides a clean, ephemeral environment that terminates after task completion.

## Summary

- **GenericAgent supports dual browser architectures**: real-browser injection via [`TMWebDriver.py`](https://github.com/lsdefine/GenericAgent/blob/main/TMWebDriver.py) and the TMWebDriver Chrome extension, or sandboxed headless automation via the MCP plugin.
- **Real-browser mode** maintains session persistence by running a WebSocket server in [`TMWebDriver.py`](https://github.com/lsdefine/GenericAgent/blob/main/TMWebDriver.py) that communicates with extension code located in `assets/tmwd_cdp_bridge/`.
- **Headless mode** bypasses extension requirements and drives a sandboxed Chromium instance directly through CDP commands, activated via `--server.headless true` in `launch.pyw` or `hub.pyw`.
- **Configuration choice** depends on whether your workflow requires existing user sessions and UI interaction (real browser) or isolated, display-free execution (sandbox/headless).

## Frequently Asked Questions

### Does GenericAgent require a Chrome extension to automate browsers?

No, the Chrome extension is only required for real-browser injection mode. When operating in sandbox/headless mode via the MCP plugin, GenericAgent communicates directly with a headless Chromium instance through the Chrome DevTools Protocol without any browser extension installed. The extension located in `assets/tmwd_cdp_bridge/` is specifically designed to bridge [`TMWebDriver.py`](https://github.com/lsdefine/GenericAgent/blob/main/TMWebDriver.py) commands to a live user browser session.

### How do I switch GenericAgent from real-browser mode to headless mode?

You switch modes by adjusting the launch parameters in `launch.pyw` or `hub.pyw`. To enable headless operation, pass `--server.headless true` to the Streamlit execution command. This configuration activates the MCP plugin pathway instead of the TMWebDriver extension bridge, effectively replacing the real-browser injection with a sandboxed headless environment.

### Can GenericAgent preserve login sessions across automation runs?

Yes, but only when using the real-browser injection pathway. The [`TMWebDriver.py`](https://github.com/lsdefine/GenericAgent/blob/main/TMWebDriver.py) implementation, combined with the TMWebDriver Chrome extension, maintains access to browser cookies, local storage, and authentication states because it operates within the user's actual browser profile. The sandbox/headless mode creates ephemeral browser instances that do not persist session data unless you manually load cookies or authentication tokens at runtime.

### What are the performance implications of TMWebDriver vs. MCP headless mode?

The TMWebDriver real-browser mode incurs slightly higher overhead due to WebSocket communication latency and the resource requirements of a visible browser window, but it provides full compatibility with JavaScript-heavy applications and multi-factor authentication flows. The MCP headless mode offers faster startup times and lower memory consumption since it runs without UI rendering, making it ideal for high-throughput scraping tasks and server environments where graphical output is unnecessary.