A native Windows Chromium browser built to be controlled through a small SDK. Open tabs, work with separate profiles, read a page as structured elements, click and type, change the viewport, and capture the visible page, a region or the full document. The browser window stays available for normal manual interaction.
Download | SDK reference | AI / MCP | API methods | Security | Validation
Français : premier essai en trois étapes.
- Extract the complete Windows x64 release ZIP and run BrowserControl.exe.
- Open a page with the address bar, create tabs and choose a profile normally.
- Connect a script with
Browser.connect(), or letBrowser.launch()start a dedicated instance automatically.
The browser uses the Microsoft Edge WebView2 Evergreen Runtime. Many Windows 10/11 PCs already have it; if it is missing, the app offers Microsoft's official download page. The browser does not silently install a runtime. No administrator rights or input driver are required.
Install the client with Python 3.10+:
python -m pip install browser-control-sdkThe package installs the SDK client. Download and open BrowserControl.exe first using step 1 above; the SDK package does not install the browser or WebView2.
Save the following as first_browser.py, then run python first_browser.py:
from browser_control import Browser
browser = Browser.connect()
tab = browser.new_tab()
tab.goto("https://example.com")
print(tab.snapshot()["text"])
tab.screenshot(path="first-page.png")Expected result: a new browser tab opens Example Domain, its visible text appears in your terminal, and first-page.png is saved in the current folder. The browser remains open for manual use.
JavaScript client: npm install browser-control-sdk. See the JavaScript SDK examples and the package table below for other clients. Installing a client never installs a product driver.
For clicks, typing and selectors, clone or download the source repository and run its owned demonstration server:
python Tests/fixture_server.py --port 8765In another terminal:
from browser_control import Browser
browser = Browser.connect()
tab = browser.new_tab()
tab.goto("http://127.0.0.1:8765")
tab.fill("Ada", selector="#name")
tab.click(selector="#save")
print(tab.snapshot()["text"])For other pages, take a snapshot and use an observed element's returned ref, name or role. Call browser.shutdown() only when you want to close that browser instance. To launch an instance from code, use Browser.launch() with the installed browser executable; a separate profile_root provides an isolated profile.
| Symptom | Next step |
|---|---|
No module named browser_control |
Use python -m pip install browser-control-sdk with the same Python used to run the script. |
| No running browser instance is found | Open the extracted BrowserControl.exe, wait for its window, then rerun the script under the same Windows user. |
| WebView2 is missing | Follow the application's official Microsoft runtime download link, then reopen the browser. |
| The local demonstration page does not load | Keep fixture_server.py running and use its printed localhost address. This server is only needed for the form example. |
| Area | SDK controls |
|---|---|
| Tabs | Create, select, inspect and close; navigation, back, forward, reload and stop |
| Page understanding | Visible text, semantic roles/names, fields, state and CSS bounds; snapshot references |
| Interaction | Click by ref, selector or position; fill, type, key down/up, shortcuts, mouse movement/buttons and wheel |
| Waiting | Wait for visible, hidden or attached targets; navigation load or DOM-ready waits and explicit timeouts |
| Images | Viewport, full-page and selected-region PNG/JPEG screenshots, live frame iterators and coordinate metadata |
| Layout | Window size/state, emulated viewport, device scale and zoom |
| Profiles | Separate persistent profiles and private contexts, with distinct cookies/session state |
| Data | Explicit cookie list/set/clear and current-origin local/session storage |
| Settings | JavaScript, devtools, context menus, status bar, zoom and user agent |
| Advanced | Page JavaScript evaluation and renderer-supported Chromium DevTools Protocol commands |
| Diagnostics | Bounded navigation/download events, operation errors, capability discovery and download controls |
The SDKs share one protocol:
| Language / client | Files |
|---|---|
| Python | browser_control.py, installable local package |
| JavaScript | browser-control.mjs, Node 18+, no npm runtime dependency |
| C++17 | BrowserControl.h and BrowserControl.cpp, with the supplied JSON header |
| AI clients | Local stdio MCP server, including screenshot image responses |
| Other languages | Length-prefixed UTF-8 JSON protocol over a private Windows named pipe |
For screenshots and frame capture, keep the browser window restored and activate
the intended tab. A minimized window reports window_minimized; call
browser.window(state="normal") explicitly before trying again. Page actions
that already completed are not repeated automatically.
These window recovery fixes are in application version 0.2.1; for an earlier
binary, restore its window manually or update. See changes.
Typed helpers cover common actions. browser.call(method, params) and the C++
Call() equivalent expose the rest without adding another integration layer.
browser.capabilities() reports the implemented methods and engine boundaries.
See Examples for independent, small scripts.
observe() returns a compact page view with labelled controls. act()
executes a finite plan in one SDK request and returns the resulting observation.
Targets accept exact accessible names and roles, selectors or snapshot refs.
page = tab.observe(max_elements=40, max_text=3000)
result = tab.act([
{"action": "fill", "name": "Your name", "role": "textbox", "text": "Ada"},
{"action": "click", "name": "Save example", "role": "button"},
], expected_generation=page["generation"])
print(result["observation"])Run this against the supplied local fixture. Plans contain at most 20 actions,
stop on the first failure and report completed steps without replaying mutations.
Optional generation/URL guards reject outdated plans. MCP browser_observe
and browser_act can use the active tab without a tab-list call.
See the AI examples.
max_elements limits returned controls. max_text limits only the returned
page-text field in UTF-8 bytes, not tokens. Names, values, URLs and other metadata
add to the response size. The top-level truncated flag records element/text
reductions made by the native response filter; it is not a completeness flag for
every individual field. See the native observation filter.
A human can sign in normally in a persistent profile. Its cookies and site storage remain with that profile when the website permits it.
For an optional password fallback, enter the credentials on the site's sign-in form and choose Logins → Save current login. Confirm the exact site and profile. Saved logins are encrypted with Windows current-user DPAPI. Use Fill saved login later, or explicitly enable automatic filling for that login. The native menu lets you choose between multiple saved accounts.
status = tab.login() # Status only.
if status["available"]:
result = tab.login("fill", submit=True) # One explicit form submission.Select credential_id= when several accounts match. Filling requires the saved
exact origin and profile. Automatic filling never submits forms; submit=True
is an explicit SDK choice and does not certify successful sign-in. Login results
and observations omit passwords. Saving/filling requires HTTPS, with loopback HTTP
allowed for the fictitious tests. Private profiles cannot use the vault.
Sites can expire cookies, require MFA/passkeys or reject embedded browsers, so some connections still need human input. Sessions and saved logins.
Connect the supplied MCP server to a client that supports local stdio tools. It can attach to an open instance or launch one on its first tool call. A typical task is: read the snapshot, select a visible target, perform the requested action, then inspect the updated state or screenshot.
Snapshots exclude password values and hidden input fields by default. Page text is untrusted website content, not an instruction source. Snapshot refs belong to one document/snapshot generation; take a fresh snapshot after navigation or a stale-ref error. Screenshots include the web page, rather than the user's entire desktop.
The current snapshot script caps individual non-sensitive
field values at 4,000 UTF-16 code units. For a long standard text control, use an
explicit evaluate() call with a known selector to read its complete .value,
or use the application's export. Virtualised editors may render only part of a
document. Read the complete source before rewriting a document, then verify the
saved result.
Each browser instance publishes a private local endpoint for its current Windows
user. The SDK discovers it automatically, or you select it explicitly. There is
no network control listener. Profiles belong to this app and remain independent
from existing Chrome/Edge profiles. Authenticate normally inside a chosen browser
profile when a site requires it; persistent profiles retain their own data.
One instance owns a data folder at a time. Connect to that instance, or select a
different private profile_root when launching another browser concurrently.
Cookie access and page evaluation are powerful explicit operations. Use private profile folders and protect endpoint files, screenshots and exported data. An operation whose result is unknown may already have executed: inspect state before retrying a click, form submission or other side effect. Security and storage.
The host limits tabs, profiles, request sizes, screenshots and event buffers. Unsupported engine operations return errors. This is a WebView2-based browser, not the entire Microsoft Edge product: Edge sync/password-manager UI, the Chrome extension store, unrestricted browser-process CDP and universal website/login compatibility are outside this version. Snapshot helpers currently cover the main frame; use renderer APIs explicitly where supported for advanced frame work. Website access controls, MFA and CAPTCHA still require the site's normal flow.
For practical examples of persistent sessions, human checkpoints and explicit tab selection, see the workflow guide and matching Python, JavaScript and C++ examples. It also explains safe continuation after a failed submission and the difference between profiles and browser instances.
Windows x64, Visual Studio 2022 C++ tools, a Windows SDK, CMake 3.24+ and Python 3.10+ for client validation:
.\Build.ps1 -TestThe build downloads a pinned, SHA-256-verified Microsoft.Web.WebView2 SDK from
NuGet on its first run. The runtime is a separate Microsoft component. Subsequent
builds can reuse obj/Dependencies. Output: obj/Build/bin/Release/BrowserControl.exe.
Building and offline checks do not open websites or install anything.
App/ Native browser, profile management and private IPC
SDK/ Python, JavaScript and C++ clients
MCP/ AI client bridge over stdio
Examples/ Small independent automation examples
Protocol/ Public method and transport reference
Tests/ Owned local fixture, integration and offline checks
ThirdParty/ Pinned dependency records and licenses
docs/ Security, validation and interface images
Project source is MIT licensed; third-party components retain their
own terms. Microsoft supplies and services the WebView2 Runtime. This app is not
endorsed by Microsoft. Use it only with systems and accounts you are authorized
to operate and follow the rules of the services you access. Supplied as-is; see
the license for warranty terms. Contact: Discord titancsa.
Les sources, licences, guides API et exemples sont regroupes dans le depot SDK dedie. Choisis le paquet a installer puis execute sa commande dans son dossier.
| Registre | Paquet | Installation / utilisation |
|---|---|---|
| vcpkg | browser-control-sdk |
vcpkg install browser-control-sdk:x64-windows |
| Conan | browser-control-sdk |
conan install --requires=browser-control-sdk/0.2.0 -r titancsa --build=missing -s compiler.cppstd=17 |
| NuGet | Browser-Control-SDK.Native |
Install-Package Browser-Control-SDK.Native -Version 0.2.0 |
| NuGet | BrowserControlSDK.SDK |
dotnet add package BrowserControlSDK.SDK --version 1.0.0 |
| PyPI | browser-control-sdk |
python -m pip install browser-control-sdk==0.2.1 |
| Conda | browser-control-sdk |
conda install --override-channels -c https://raw.githubusercontent.com/TitanCSA/sdk-packages/089bc73095aa8eda89bacbe10d0b9e58394b0207/conda-channel -c conda-forge browser-control-sdk (canal TitanCSA) |
| crates.io | browser-control-sdk |
cargo add browser-control-sdk@1.0.0 |
| npm | browser-control-sdk |
npm install browser-control-sdk@0.2.1 |
| Maven Central | io.github.titancsa:browser-control-sdk |
io.github.titancsa:browser-control-sdk:1.0.0 (pom.xml / Gradle) |
| JitPack | com.github.TitanCSA:Browser-Control-SDK |
com.github.TitanCSA:Browser-Control-SDK:java-sdk-v1.0.0 (avec le depot JitPack) |
| Go Modules | github.com/TitanCSA/Browser-Control-SDK/Browser-Control-SDK-Go-modules |
go get github.com/TitanCSA/Browser-Control-SDK/Browser-Control-SDK-Go-modules@v0.2.1 |
| pkg.go.dev | github.com/TitanCSA/Browser-Control-SDK/Browser-Control-SDK-Go-modules |
Documentation : https://pkg.go.dev/github.com/TitanCSA/Browser-Control-SDK/Browser-Control-SDK-Go-modules@v0.2.1 |
| PowerShell Gallery | BrowserControlSDK |
Install-Module BrowserControlSDK -RequiredVersion 0.2.1 -Scope CurrentUser |
| pub.dev | browser_control_sdk |
dart pub add browser_control_sdk:0.2.1 |
| RubyGems | browser-control-sdk |
gem install browser-control-sdk -v 0.2.2 |
| Packagist | titancsa/browser-control-sdk |
composer require titancsa/browser-control-sdk:1.0.0 |
Pour vcpkg et Conan, configure d abord le registre TitanCSA avec le guide complet. Le guide explique aussi Maven/Gradle, les prerequis et le chargement des DLL. Les pilotes/applications du produit sont installes separement. Les commandes marquees prevues ne sont pas encore disponibles.
Les anciens imports Go et versions JitPack gardent leurs tags. Pour les anciennes archives SDK, utilise les liens de remplacement.
