dwbrowser

README

deepwork-browser

A browser automation engine built on Chrome DevTools Protocol (CDP). Provides a managed Chrome pool, session lifecycle, LiveView HTTP streaming, and a CLI for scripted browser tasks.

Features

• Chrome pool with configurable concurrency
• Session-based tab management with target tracking
• LiveView: real-time DOM/screenshot streaming over HTTP
• Snapshot: full-page capture (HTML + screenshot)
• Action execution: click, type, scroll, evaluate
• SQLite-backed session persistence
• CLI tool (dw-browser) for scripted automation

Quick Start

go get github.com/brightman-ai/deepwork-browser

Or run the CLI:

go run ./cmd/dw-browser --help

# Open a URL and take a screenshot
dw-browser open https://example.com
dw-browser snap --out screenshot.png

Embed the HTTP server:

import browser "github.com/brightman-ai/deepwork-browser"

srv := browser.New(browser.DefaultConfig())
http.Handle("/browser/", srv.Handler())

See guide/ for full documentation.

License

MIT

Documentation

Index

• type Config
  • func DefaultConfig() Config
• type Hooks
• type Option
  • func WithAddr(addr string) Option
  • func WithConfig(c Config) Option
  • func WithDataDir(dir string) Option
  • func WithHeadless(v bool) Option
  • func WithHooks(h Hooks) Option
• type Server
  • func NewServer(opts ...Option) (*Server, error)
  • func (s *Server) Close() error
  • func (s *Server) Handler() http.Handler
  • func (s *Server) ListenAndServe(ctx context.Context) error
  • func (s *Server) Pool() *browser.BrowserPool
  • func (s *Server) Port() int
• type WorkspaceLauncher

Types

type Config

type Config struct {
	Addr     string
	Headless bool
	PoolSize int
	DataDir  string
}

Config holds configuration for the browser server.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type Hooks

type Hooks struct {
	// OnNavigate is called when a session navigates to a new URL.
	OnNavigate func(ctx context.Context, sessionID string, url string) error

	// OnPageLoad is called when a page finishes loading.
	OnPageLoad func(ctx context.Context, sessionID string, title string) error

	// WorkspaceLauncher integrates with an external workspace manager
	// (e.g., macOS virtual display spaces). Optional.
	WorkspaceLauncher WorkspaceLauncher
}

Hooks allows the host application to intercept browser events.

type Option

type Option func(*Server)

Option is a functional option for Server.

func WithAddr

func WithAddr(addr string) Option

WithAddr sets the listen address.

func WithConfig

func WithConfig(c Config) Option

WithConfig sets the full Config.

func WithDataDir

func WithDataDir(dir string) Option

WithDataDir sets the data directory for browser profiles.

func WithHeadless

func WithHeadless(v bool) Option

WithHeadless sets headless mode.

func WithHooks

func WithHooks(h Hooks) Option

WithHooks sets the Hooks.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server provides browser automation as an embeddable HTTP service.

Usage (embedded):

srv, _ := dwbrowser.NewServer(dwbrowser.WithAddr(":8033"))
mux.Handle("/browser/", http.StripPrefix("/browser", srv.Handler()))

Usage (standalone):

srv, _ := dwbrowser.NewServer()
srv.ListenAndServe(ctx)

func NewServer

func NewServer(opts ...Option) (*Server, error)

NewServer creates a Server with the provided options.

func (*Server) Close

func (s *Server) Close() error

Close shuts down the server and the underlying browser pool.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns an http.Handler for embedding into an existing mux. Routes are relative (no /api/ prefix); the caller may add a prefix via http.StripPrefix if needed.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(ctx context.Context) error

ListenAndServe starts a standalone HTTP server on s.config.Addr. It blocks until ctx is cancelled.

func (*Server) Pool

func (s *Server) Pool() *browser.BrowserPool

Pool returns the underlying BrowserPool for programmatic access. May return nil if the pool has not been initialized yet.

func (*Server) Port

func (s *Server) Port() int

Port returns the TCP port the server is listening on. Returns 0 if ListenAndServe has not been called.

type WorkspaceLauncher

type WorkspaceLauncher interface {
	// LaunchChromeInSpace launches Chrome in a dedicated workspace space.
	// Returns the Chrome DevTools WebSocket URL and the process PID.
	LaunchChromeInSpace(ctx context.Context, profile string) (wsURL string, pid int, err error)
}

WorkspaceLauncher abstracts launching Chrome inside a managed workspace/space.