English | 中文

Tap into your live browser. Close the agent loop. Built in Rust.

browsertap lets AI agents and CLI tools control an already-open, already-authenticated browser session -- screenshots, JS execution, smoke tests, console capture, and more -- without spinning up headless instances or re-logging in.

AI agents that interact with web apps need to see and control the real thing. They need to run JS, take screenshots, check console errors, and click buttons -- all in a browser that's already logged in with real cookies, real sessions, and real state.

Existing tools don't fit this workflow:

The typical AI agent workflow with browsertap:

Developer has web app open in browser (already logged in)
        |
        v
@browsertap/runtime connects the tab to the daemon
        |
        v
AI agent runs: browsertap run-js iron-falcon "document.title"
        |
        v
AI agent runs: browsertap screenshot iron-falcon -o page.jpg
        |
        v
AI agent inspects the screenshot / queries DOM / checks console
        |
        v
AI agent runs: browsertap smoke iron-falcon --preset main
        |
        v
No headless browser. No re-login. No lost state.

• Attach to live sessions -- Control an already-open, already-authenticated browser tab
• Daemon architecture -- browsertapd runs as a persistent HTTPS + WebSocket hub; CLI commands talk to it via REST API
• Session codenames -- Friendly names like iron-falcon or calm-otter instead of UUIDs
• JavaScript execution -- Run arbitrary JS in the browser context via CLI
• Screenshot capture -- Full page or element-specific via CSS selector
• Console capture -- View browser console output with level filtering; buffer survives CLI reconnect
• Network capture -- Inspect HTTP requests/responses buffered by the runtime
• Smoke testing -- Automated route sweep with presets, error detection, and progress tracking
• Selector discovery -- Find interactive elements on the page (buttons, links, inputs)
• HMAC-SHA256 tokens -- Short-lived session tokens (5 min) and CLI tokens (1 hour)
• Self-signed TLS -- Auto-generated certificates via rcgen + rustls, zero external tools
• Auto-reconnect -- Browser runtime reconnects with exponential backoff after disconnects
• Config file walk-up -- Place browsertap.toml at project root; CLI finds it automatically
• JSON output -- Machine-readable output for agent integration
• Cross-platform -- macOS, Linux, and Windows

cargo install browsertap-cli
cargo install browsertap-daemon

Download from GitHub Releases:

npm install @browsertap/runtime

git clone https://github.com/justinhuangcode/browsertap.git
cd browsertap
cargo build --release
# Binaries at: target/release/browsertap, target/release/browsertapd

Requirements: Rust 1.75+ and a Chromium-based browser for the page you want to control.

browsertapd
# => browsertapd listening on https://127.0.0.1:4455

import { createBrowserTapClient, createSessionStorageAdapter } from '@browsertap/runtime';

const client = createBrowserTapClient({
  storage: createSessionStorageAdapter(),
  onStatus: (snap) => console.log('browsertap:', snap.status, snap.codename),
  autoReconnectHandshake: () =>
    fetch('/api/browsertap/handshake', { method: 'POST' }).then(r => r.json()),
});

const handshake = await fetch('/api/browsertap/handshake', { method: 'POST' }).then(r => r.json());
await client.startSession(handshake);
// => "connected as iron-falcon"

browsertap sessions
# CODENAME             URL                                      STATE      HEARTBEAT
# iron-falcon          http://localhost:3000/dashboard           open       2s ago

browsertap run-js iron-falcon "document.title"
# "Dashboard - MyApp"

browsertap screenshot iron-falcon --selector "#analytics" -o card.jpg
# Screenshot saved to card.jpg (45832 bytes)

1. browsertapd starts an HTTPS + WebSocket server on 127.0.0.1:4455. It auto-generates self-signed TLS certificates on first run and stores them at ~/.browsertap/certs/.

2. Your web app embeds @browsertap/runtime. When activated, the runtime calls your backend's handshake endpoint, which mints an HMAC-SHA256 signed session token using the shared secret.

3. The browser runtime opens a WebSocket to the daemon, sends a register message with the signed token, and receives a friendly codename (e.g., iron-falcon). It then patches console.* to capture logs and starts a heartbeat every 5 seconds.

4. CLI commands (browsertap run-js iron-falcon "...") send HTTPS requests to the daemon's REST API. The daemon forwards the command to the browser via WebSocket, waits for the result, and returns it to the CLI.

5. Console and network events are buffered in the daemon (500 console events, 200 network events per session). The CLI can retroactively query these buffers, even for events that occurred before the CLI connected.

                            WebSocket (wss://)
+------------------+                                +------------------+
|  Your Web App    |  ------>  +--------------+     |  CLI / AI Agent  |
|  (logged in)     |  <------  |  browsertapd |     |                  |
|                  |           |              |     |  $ browsertap    |
| @browsertap/     |  register |  Session     | <-- |    run-js        |
|   runtime        |  heartbeat|  Registry    | --> |    screenshot    |
|                  |  console  |  Command     |     |    smoke         |
|                  |  result   |  Router      |     |    console       |
+------------------+           |  TLS (rustls)|     +------------------+
                               +--------------+
                                 HTTPS REST API

Create browsertap.toml at your project root. The CLI walks up directories to find it.

app_label = "MyApp"
app_url = "http://localhost:3000"
daemon_url = "https://127.0.0.1:4455"

[daemon]
host = "127.0.0.1"
port = 4455

[smoke]
defaults = ["dashboard", "settings", "profile"]

[smoke.presets]
main = ["dashboard", "settings", "profile", "billing"]
quick = ["dashboard"]

[smoke.redirects]
"/" = "/dashboard"

Resolution order: CLI flags > Environment variables > browsertap.toml > Defaults

Your web app backend needs one endpoint to mint session tokens:

// POST /api/browsertap/handshake
import { readFileSync } from 'fs';
import { createHmac, randomUUID } from 'crypto';

export async function POST() {
  const secret = process.env.BROWSERTAP_SECRET
    ?? readFileSync(`${process.env.HOME}/.browsertap/secret.key`, 'utf8').trim();

  const sessionId = randomUUID();
  const payload = {
    token_id: randomUUID(),
    scope: 'session',
    subject: 'browsertap-web',
    session_id: sessionId,
    issued_at: new Date().toISOString(),
    expires_at: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
  };

  const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const sig = createHmac('sha256', Buffer.from(secret, 'hex'))
    .update(encoded).digest('base64url');

  return Response.json({
    sessionId,
    sessionToken: `${encoded}.${sig}`,
    socketUrl: 'wss://127.0.0.1:4455/bridge',
    expiresAt: Math.floor(Date.now() / 1000) + 300,
  });
}

browsertap is designed for single-user, local-only use on development machines.

• Multi-user / shared machines -- Other local users with root access can read the session token
• Production workloads -- browsertap is a development/testing tool; no rate limiting or audit logging
• Untrusted networks -- Self-signed certificates are not verified by default

browsertap/
├── Cargo.toml                    # Workspace root
├── browsertap.toml               # Example project config
├── crates/
│   ├── shared/                   # Shared library (tokens, protocol, types)
│   │   └── src/
│   │       ├── lib.rs            # Module exports
│   │       ├── token.rs          # HMAC-SHA256 token sign/verify
│   │       ├── protocol.rs       # WebSocket + REST protocol types
│   │       ├── session.rs        # Session state, config types
│   │       └── codename.rs       # Friendly codename generation
│   ├── daemon/                   # Daemon binary (browsertapd)
│   │   └── src/
│   │       ├── main.rs           # Axum HTTPS server + REST routes
│   │       ├── state.rs          # Session registry, command routing
│   │       ├── websocket.rs      # WebSocket handler (register/heartbeat/command)
│   │       └── tls.rs            # Self-signed cert generation (rcgen)
│   └── cli/                      # CLI binary (browsertap)
│       └── src/
│           ├── main.rs           # Clap command definitions
│           ├── client.rs         # HTTP client for daemon REST API
│           └── config.rs         # browsertap.toml loader (walk-up)
└── runtime/
    └── browser/                  # Browser runtime SDK (TypeScript)
        ├── package.json          # @browsertap/runtime
        ├── tsconfig.json
        └── src/
            ├── index.ts          # Public API exports
            ├── client.ts         # WebSocket lifecycle, command executor, console patch
            ├── types.ts          # TypeScript type definitions
            └── storage.ts        # Session persistence adapters

Contributions are welcome! Please open an issue to discuss your idea before submitting a PR.

See Releases for version history.

MIT