Tabora Browser

Local browser control for AI agents, through MCP. A Manifest V3 extension executes bounded DOM actions; a small local host routes profiles and optionally stores encrypted credentials. MIT licensed. Windows preview; Chrome, Edge and bundled Chromium. The extension UI is currently in Czech; MCP tool descriptions are in English.

Quick start

Prerequisites: Windows 10/11, Git and Node.js 22 or newer. Install in a permanent, user-owned directory; MCP and native messaging use its absolute path. No administrator rights are needed.

git clone https://github.com/halatao/tabora-browser.git
cd tabora-browser
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/setup.ps1 -Managed -Client auto

This installs locked npm dependencies, builds the extension/host, registers the native host for the current Windows user, registers MCP with Codex and/or Claude Code when their CLI is on PATH, installs Playwright Chromium, and opens a dedicated default profile with the extension loaded and MCP enabled. A real stdio MCP handshake and profile discovery complete setup. Restart the MCP client to load the new server.

For an agent running without a visible browser, and with access to an explicitly selected site:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/setup.ps1 -Managed -Client codex -Profile work -AllowOrigin https://example.com -Headless

Use -Client claude, both, or none to choose registration. auto skips missing CLIs; explicitly requesting a missing CLI fails with instructions. Model API keys are not required when the calling agent chooses actions through MCP. Codex and Claude can use existing local SDK login; Jev reads TYPESAFE_API_KEY (or JEV_API_KEY). Provider API keys can optionally be stored in the vault.

The extension requests access to HTTP(S) sites once during installation, so there is no per-site setup in the panel. Browser consent and enterprise policies still apply. Managed profiles inherit this default; passing -AllowOrigin restricts that managed copy to the listed sites. Multiple origins can be passed as a PowerShell array when invoking ./scripts/setup.ps1 directly. Chrome host permissions cover all ports on the specified hostname; vault credential use additionally checks the exact HTTPS origin including port. The browser helper uses normal TLS verification.

Related MCP server: project-tendril

Managed profiles

npm run browser -- start --profile work --allow-origin https://example.com
npm run browser -- status --profile work
npm run doctor -- --require-profile
npm run browser -- stop --profile work

Each name gets a separate persistent Chromium profile and extension identity within that profile. Repeating start returns the running instance. To add a permitted origin, stop the profile and start it again with --allow-origin; previous origins persist. First setup enables MCP; later starts preserve a user's disabled MCP setting. Use --enable-mcp explicitly on a stopped profile to enable it again. To change a managed restriction, stop the profile and update its local config.json, then restart. An empty origin list uses the extension’s default HTTP(S) access.

The browser runs as a background Node process until stopped or its window is closed. Control uses a local Windows named pipe, with no remote debugging TCP port. Stop targets only that managed profile. Do not use a managed profile directory with another browser process.

Existing Chrome / Edge profile

Run setup without -Managed, then:

1. Open chrome://extensions or edge://extensions in the intended profile.

2. Enable Developer mode, choose Load unpacked, and select this checkout's dist/extension.

3. Open Tabora’s side panel or extension options. Connection starts automatically; new profiles enable MCP, use Safe mode, and keep the vault off.

4. Run npm run doctor -- --require-profile.

Repeat the load steps for other browser profiles. The name is read from Chrome/Edge profile metadata when exactly one matching installed profile can be identified. Chrome does not expose the display name directly to extensions. If multiple profiles match, choose the profile once in Settings; Tabora does not guess from “last used”. Managed profiles use their launcher name. Existing explicit MCP revocation is preserved. Their profile IDs are distinct. This project is not published to the Chrome Web Store; it does not silently install into ordinary Chrome profiles or bypass browser policy. Chrome installation rules explain that boundary. The automatic route follows Playwright's Chromium extension support.

Three browser modes

The main panel contains the mode, provider, model select and vault switch. Manual controls and diagnostics are collapsed; settings are secondary.

Safe shares the current profile’s cookies and website login; it is not incognito or a separate account sandbox. Read only prevents Tabora actions from changing page content, not the site’s own JavaScript/network activity. Changing modes invalidates prepared actions and document bindings. Disabling the vault revokes credential access and locks this profile’s grant without deleting saved secrets. The main Stop button cancels all sessions in this profile.

The vault switch is off for new installations and migration from profiles without the switch. Enabling it reveals vault management; unlocking is a separate explicit action. MCP and site consent are independent of vault access.

MCP clients and actions

The setup script uses the clients' supported registration commands. For other stdio clients, merge the generated, git-ignored mcp.config.json entry into their configuration. It points to the installed Node executable and dist/host/mcp.js; do not commit this machine-specific file. This is a local stdio server, not a hosted URL usable directly from a cloud ChatGPT connector.

References: Codex MCP, Claude Code MCP.

The server exposes 13 tools. Typical flow:

1. browser_profiles → choose a profile ID; browser_tabs lists its tabs.

2. browser_session_create with a meaningful task name.

3. browser_session_open opens a link in that session’s named tab group (and new window in Safe), or select an existing tab in Takeover/Read only.

4. After navigation completes, browser_session_attach binds the exact tab/document.

5. browser_observe with recipe click, fill, login, or extract. Read only permits extract only; login requires the enabled/unlocked vault.

6. The agent chooses a target and calls browser_prepare. Alternatively browser_decide asks one of the configured decision adapters.

7. browser_execute with the returned single-use action ID; inspect the actual result before continuing.

8. browser_session_release releases ownership, leaving tabs open.

browser_sessions, browser_cancel, and browser_vault_list support inspection, cancellation and credential metadata. Each MCP connection owns its sessions; one session owns an attached tab. Different sessions/profiles can work concurrently. Navigation invalidates prepared actions; reattach and observe. If the host restarts, MCP stdio stays alive and reconnects on the next request. Existing sessions are lost; discover the profile and create a new session. In-flight actions fail without automatic replay. Click dispatch is not proof that the website completed the intended operation. Do not automatically retry ambiguous actions.

Optional vault and decision providers

Vault is off by default. Setup and explicit unlock happen in the extension panel. Credentials can be shared across profiles or restricted to one profile (the default). Each profile has its own unlock grant and timeout. Website login uses a credential ID and fills only the bound exact HTTPS origin. Passwords and provider keys are not returned through MCP or sent to decision models.

The vault uses AES-256-GCM with a Windows DPAPI-protected key. It is local to the Windows user, with no biometric challenge, cloud sync or cross-machine recovery. Profile scoping is enforced by the application; it is not a security boundary against arbitrary processes running as the same Windows user. Deleting the encryption key can make saved credentials unrecoverable.

Select a provider, connect its SDK/catalog, then select a model. No free-text model field is used. Codex model choices come from App Server model/list; Claude from supportedModels(); Jev from its authenticated /v1/models. Optional Codex API-key mode lists text-model families from the OpenAI API catalog. A catalog is not proof of entitlement or structured-output compatibility; the first decision validates actual access. Catalogs are cached for five minutes and the Connect button refreshes them. SDK authentication remains with the local provider client; Tabora neither imports credentials into the vault nor unlocks it automatically. If the SDK reports login_required, sign in through that provider’s local client and reconnect.

The default Connected agent / MCP provider lets the calling agent choose via browser_prepare, avoiding an extra model call. browser_profiles returns activeProvider as the profile’s preference; an explicitly supplied browser_decide provider remains supported for comparisons. Adapters only choose among observed targets; the extension alone executes actions. No performance superiority over Codex/ChatGPT’s extension is claimed by these installation tests.

API references: Codex App Server, Claude Agent SDK, Jev OpenAPI, OpenAI model catalog.

Data, updates and removal

Default data directory: %LOCALAPPDATA%\TaboraBrowser. Installation resolves its physical Windows location and saves it in the generated dist/native-host/state.json; the native host, MCP server and managed browser all use that location. This also handles Microsoft Store/MSIX clients whose AppData writes are redirected into a package's LocalCache. Existing data stays in place. If the resolved location is inside a client package, uninstalling that client can remove it; use an explicit TABORA_STATE_DIR outside the package for storage independent of the client. Managed profiles live under managed\<name>; their config.json contains allowed origins and browser.log contains startup diagnostics. TABORA_STATE_DIR overrides the root; use the same absolute directory for browser and MCP. Setup carries an explicitly set override into MCP registration. The original Browser Pilot prototype has a separate host identity and data directory; nothing is imported automatically.

To update, stop managed profiles, git pull --ff-only, then rerun setup. Reload unpacked extensions in ordinary profiles. Do not move/delete the checkout while installed. Registrations are idempotent for the same checkout; a different checkout produces a conflict instead of replacing it.

To uninstall, stop each managed profile, remove Tabora from the browser's extensions, run scripts/uninstall-host.ps1, and remove the MCP entry from clients that registered it (codex mcp remove tabora-browser / claude mcp remove tabora-browser --scope user). Vault and browser data are retained. Remove them only if you explicitly want to discard those accounts and credentials.

Development and validation

npm ci
npm run check
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/install-host.ps1
npx playwright install chromium
npm run test:native
npm run test:managed
npm run test:mcp
npm run test:mcp-legacy
npm run test:browser
npm run test:sdk

Tests use synthetic pages and credentials; SDK smoke tests use synthetic API responses. No paid model calls or real vault are required. Windows CI validates the build, native messaging, managed setup, multiple profiles, vault scoping and MCP compatibility. Generated state and reports are ignored by Git. extension-key.txt is a public key committed to keep the extension ID stable; there is no signing private key in the repository.

Current scope: main-document DOM controls, visible text (16,000 characters) and bounded tables/forms. Iframes, shadow DOM, canvas, CAPTCHA/MFA automation and trusted OS input are unsupported. macOS/Linux native installation and secure key storage are not implemented. This is an early preview, not an audited password manager.

If the native host is unavailable, inspect the diagnostic code in the panel: native_host_not_registered means Chrome could not find the registration, native_host_forbidden indicates an origin or browser-policy restriction, native_host_start_failed means Chrome could not launch the process, native_host_exited means the process stopped, and native_host_protocol_error indicates invalid native messaging. Rerun setup from the original checkout when registration or launcher paths are incorrect, then inspect npm run doctor. After rebuilding, reload the unpacked extension on the browser's extensions page; the panel's refresh button only reconnects the currently loaded code. If no profiles appear, start the managed browser or enable MCP in the intended ordinary profile. A missing client CLI does not prevent generic stdio MCP use. For a stale managed-process lock, inspect the matching process and profile before removing process.json; never close all Chrome processes.

License

MIT.