Awesome browserkit exposes Chrome / Chromium page operations, live frame streaming, and diagnostics to agents and applications. Agents use the CLI or Go functions to inspect pages, interact with elements, and manage tabs. Users can watch execution, enter input, and take control through a React interface. The browser can run locally, on a remote server, or as an existing browser with CDP debugging enabled.
BrowserView is mounted directly in the workspace content area—without an extra browser card around it.
F12 Developer tools — click to open or close
Control handoff — click to show or hide
The surrounding workspace and page contents are illustrative. The embedded panel renders tabs, the address bar, browser input, control handoff, and diagnostics inside the host application's container. Run the interactive demo.
| Capability | Details |
|---|---|
| Attach to an existing browser | Connect to an authorized Chrome / Chromium instance with its cookies, signed-in sessions, and page context. Attach to the active tab by default; disconnecting preserves the browser and its tabs. |
| Isolated browser environments | The CLI's new mode launches a headless browser with a temporary profile. Cookies and local storage are isolated from the everyday browser and other client processes. The profile is removed on exit. |
| Agent page operations | Snapshots provide page text, element references, and revision information. Click, hover, type, press keys, navigate, wait, capture screenshots, and manage tabs through functions that can be registered as tools in a host framework. |
| Live frame streaming | Browser frames travel over WebSocket and scale to the component container. Go quality presets configure frame rate and JPEG quality. Slow connections skip older frames to limit backlog. |
| Remote visual interaction | The React interface includes tabs, an address bar, mouse, touch, wheel, keyboard, and IME input. Input is executed on the browser host; resulting page changes return through the frame stream. |
| Shared viewing and control | Multiple clients can observe a session, with input coordinated through control ownership. Users can take control, while server-enforced read-only endpoints support observation of agent activity. |
| Diagnostics | Inspect console output, runtime exceptions, network requests, and page resources. The F12 panel provides filtering and details; agents can read records through diagnostic functions. |
| Configurable UI | Configure regions, buttons, input types, keyboard activation, and diagnostic panels per client. Customize appearance and dimensions with CSS variables, classes, and style. |
The diagnostic panel supports Console, Network, and Resources; it does not currently include Elements editing or JavaScript breakpoints. Sessions are held in memory and are not restored after a service restart.
flowchart LR
Agent[Agent] --> CLI[CLI + Skill]
Agent --> Tool[Go Function Tool]
User[User] <--> React[React BrowserView]
React <-->|HTTP / WebSocket| HTTP[HTTP Handler / Server]
CLI --> Manager[Go Manager]
Tool --> Manager
HTTP <--> Manager
Manager <-->|CDP| Browser[Local or remote Chrome / Chromium]
The CLI, Go functions, and HTTP handler use Manager to manage sessions and pages.
React displays browser frames and forwards input; page scripts and network requests execute in Chrome / Chromium.
| Integration | Use case | Guide |
|---|---|---|
| Local Skill | Let an agent use existing local sign-in state or browse in an isolated environment | CLI and Skill |
| Standalone service | Run browsers on a server and let clients view and interact remotely | HTTP service |
| Embedded library | Add browser operations and visualization to an agent product, workbench, or application | Go and React |
- Go 1.25.8+.
- Chrome / Chromium on the machine running the browser.
- Node.js 22+ to build the React component or demo. The component supports React 19.
git clone https://github.com/zeoxisca/awesome-browserkit.git
cd awesome-browserkit
go mod downloadRun build commands from the repository root and dependency installation commands from the consuming application.
The installer builds the client and configures its Agent Skill. Codex is the default target:
./install.sh
export PATH="$HOME/.local/bin:$PATH"
browserkit --versionThe default client directory is ~/.local/bin.
The default Codex Skill directory is ${CODEX_HOME:-~/.codex}/skills/browserkit-cli.
Configure the same Skill for Pi Agent, or for both agents:
./install.sh --agent pi
./install.sh --agent allPi installs the Skill under ${PI_CODING_AGENT_DIR:-~/.pi/agent}/skills/browserkit-cli; start a new Pi session and use /skill:browserkit-cli to invoke it explicitly. Override destinations with BROWSERKIT_BIN_DIR, BROWSERKIT_CODEX_SKILL_DIR, or BROWSERKIT_PI_SKILL_DIR. The legacy BROWSERKIT_SKILL_DIR override remains supported for a selected target.
Agent usage instructions are in the Skill.
Open chrome://inspect/#remote-debugging in Chrome and enable Allow remote debugging for this browser.
If that option is unavailable, upgrade Chrome.
Note the debugging address, return to the target tab, and accept Chrome's connection prompt when it appears.
browserkit --mode attach --remote 'http://127.0.0.1:9222'Replace the example address with the actual CDP endpoint: HTTP /json/version or a browser WebSocket URL.
By default, the client attaches to the focused tab, falling back to the only visible tab when Chrome is unfocused.
If multiple windows make the target ambiguous, focus the target page and try again.
Exiting the client disconnects without closing the browser or its tabs.
browserkit --url 'https://example.com'The default new mode runs headless with a temporary profile.
Cookies and local storage are isolated from the everyday browser; exiting closes the browser and removes the profile.
Without --url, the agent creates a page through a tool call.
In every mode, --url creates a new tab in the selected browser and opens the address, even if a tab with the same URL already exists.
For example, open a new tab in an existing browser:
browserkit --mode attach --remote 'http://127.0.0.1:9222' --url 'https://example.com/workspace'make server
./browserkit-server --addr 0.0.0.0:8787 \
--url https://example.com \
--allowed-origins https://app.example.comThe default listen address is 127.0.0.1:8787.
Browser endpoints are under /browser; /healthz provides a health check.
Use --remote to connect to an existing browser. Without --url, the service waits for a client to create a page.
--allowed-origins accepts a comma-separated list of frontend origins.
Install the React component, then connect to the service:
import { BrowserView } from '@browserkit/react'
import '@browserkit/react/style.css'
export function RemoteBrowser() {
return <BrowserView
endpoint="https://browser.example.com/browser"
style={{ width: '100%', height: 640 }}
/>
}go get github.com/zeoxisca/awesome-browserkitimport (
"context"
"net/http"
"os"
browserkit "github.com/zeoxisca/awesome-browserkit"
"github.com/zeoxisca/awesome-browserkit/browserhttp"
)
func mountBrowser(ctx context.Context, mux *http.ServeMux) (*browserkit.Manager, error) {
manager, err := browserkit.NewManager(browserkit.Config{AllowDevtools: true})
if err != nil { return nil, err }
if _, err = manager.Open(ctx, browserkit.OpenRequest{URL: "https://example.com"}); err != nil {
_ = manager.Close(context.Background())
return nil, err
}
mux.Handle("/browser/", http.StripPrefix("/browser",
browserhttp.NewHandler(manager, browserhttp.Options{})))
return manager, nil
}browserhttp.Options.AuthMiddleware uses the standard Go HTTP middleware shape, so the host can plug in Bearer tokens, cookie sessions, mTLS identities, or authenticated reverse-proxy headers. It runs before every BrowserKit route and protects both regular HTTP requests and WebSocket handshakes:
authenticate := func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Header.Get("Authorization") != "Bearer "+os.Getenv("BROWSERKIT_TOKEN") {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
next.ServeHTTP(w, r)
})
}
handler := browserhttp.NewHandler(manager, browserhttp.Options{
AuthMiddleware: authenticate,
})This is an interface example only; production deployments should use the host's identity system and constant-time token checks. AllowedOrigins limits browser cross-origin calls but is not authentication.
Browser access to loopback, private, link-local, and other non-public addresses is denied by default. Built-in Rod/CDP sessions resolve and inspect every destination IP before each HTTP(S) or WebSocket request, including redirects, iframes, scripts, images, and XHR/Fetch resources. When AllowedOrigins is configured, every Document navigation and redirect hop is also checked against it. Set AllowPrivateNetwork: true only for trusted local development. A custom SessionFactory must enforce an equivalent policy in its own browser transport.
Call manager.Close(context.Background()) when the application exits.
Manager.Functions() returns tools bound to that manager:
Pass each function’s Name, Description, and Handler to the host tool registry.
Handler has the signature func(context.Context, Request) (Response, error).
Requests and responses are exported named structs. The host provides schema validation and the tool invocation protocol. See examples/functions for an adapter example.
After installing the component:
import { BrowserView } from '@browserkit/react'
import '@browserkit/react/style.css'
export function BrowserPanel() {
return <BrowserView endpoint="/browser" style={{ height: 560 }} />
}See the React API for UI, input, and diagnostic options. The detailed API and Skill documentation are currently in Chinese.
The component is not yet published to npm. Build a package in the Awesome browserkit repository:
npm ci --prefix react
make packInstall it in the React application, replacing the package path:
npm install /path/to/awesome-browserkit/react/browserkit-react-0.1.0.tgzIf the application does not already use React 19:
npm install react@^19 react-dom@^19Install Go 1.25.8+, Node.js 22+, and Chrome / Chromium, then run:
git clone https://github.com/zeoxisca/awesome-browserkit.git
cd awesome-browserkit
make install
make build
make demoIf you already have the source, run the last three commands from the repository root.
make demo starts the Go service and browser with a bundled example page.
Open the workbench or quick start.
Press Ctrl+C to stop the service and browser.
To use another port or Chrome executable:
go run ./examples/demo --addr 127.0.0.1:8878 --chrome /path/to/chromeSee Contributing for development and test commands.