Browser

The Browser represents a running Chrome instance. It manages the WebSocket connection, browser contexts, and the Chrome process lifecycle.

Launch

Start a new Chrome process:

b, err := bonk.Launch()
if err != nil {
    log.Fatal(err)
}
defer b.Close()

Launch Options

b, err := bonk.Launch(
    bonk.Headless(false),              // show browser window
    bonk.Stealth(true),                // anti-detection (default: true)
    bonk.ChromePath("/usr/bin/chromium"), // explicit binary path
    bonk.UserDataDir("./profile"),     // persistent profile directory
    bonk.Args("--proxy-server=socks5://localhost:1080"),
    bonk.Env("DISPLAY=:1"),
    bonk.WithLogger(slog.Default()),   // log all CDP messages
)

Option	Default	Description
`Headless(bool)`	`true`	Run Chrome without a visible window
`Stealth(bool)`	`true`	Enable anti-detection measures
`ChromePath(string)`	auto-detect	Path to Chrome binary
`UserDataDir(string)`	temp dir	User data directory (temp dir cleaned up on Close)
`Args(...string)`	—	Additional Chrome command-line flags
`Env(...string)`	—	Additional environment variables
`WithLogger(*slog.Logger)`	—	Enable CDP message logging

Connect to Existing Browser

Attach to a Chrome instance that's already running with --remote-debugging-port:

b, err := bonk.Connect("ws://localhost:9222/devtools/browser/...")
if err != nil {
    log.Fatal(err)
}
defer b.Close()

Connect accepts the same LaunchOption values for configuration:

b, err := bonk.Connect(wsURL, bonk.WithLogger(slog.Default()))

Create Contexts

ctx, err := b.NewContext()

See Context for context options.

Close

Close() performs a graceful shutdown:

Disposes all browser contexts and their pages
Sends Browser.close CDP command
Waits up to 5 seconds for the process to exit
Sends SIGTERM, waits another 5 seconds
Sends SIGKILL if still running
Cleans up temporary directories

b.Close()

Connection Recovery

If the WebSocket connection drops unexpectedly, you can reconnect:

b.OnDisconnect(func() {
    log.Println("connection lost, reconnecting...")
    if err := b.Reconnect(); err != nil {
        log.Fatal("reconnect failed:", err)
    }
})

Reconnect() re-dials the stored WebSocket URL, creates a new RPC connection, and restarts the message listener. Existing browser contexts and pages will need to be re-created.