steel-browser

Provides full programmatic control over Chrome instances via the Chrome DevTools Protocol through a CDPService abstraction layer that manages browser lifecycle, navigation, DOM interaction, and JavaScript execution. Sessions are persisted with stateful context through SessionService and ChromeContextService, enabling multi-step automation workflows where browser state (cookies, local storage, DOM) survives across API calls. The architecture uses puppeteer-core as the underlying CDP client, abstracting away low-level protocol details while exposing high-level browser operations through REST endpoints.

Implements fingerprint spoofing and stealth features through fingerprint-generator and fingerprint-injector modules that mask browser automation signals and randomize device fingerprints to evade bot detection systems. The system injects synthetic user-agent strings, screen resolutions, timezone data, and WebGL parameters that mimic real user devices, reducing detection likelihood on sites with anti-bot measures. This is critical for AI agents accessing protected or rate-limited web services that actively block automated access.

Provides REST API endpoints for monitoring active sessions, checking browser health, and retrieving session metadata in real-time. The system exposes endpoints to list active sessions, get session details (uptime, resource usage, event count), and perform health checks on browser instances. This enables external monitoring systems and dashboards to track Steel Browser health and session status.

Automatically generates OpenAPI schema from REST API route definitions and provides generated API clients with full TypeScript type safety. The system uses OpenAPI tooling to introspect the API surface and generate client libraries, enabling developers to interact with Steel Browser with IDE autocomplete and compile-time type checking. This reduces integration friction and prevents runtime errors from incorrect API usage.

Provides Docker containerization through a Dockerfile that packages Steel Browser with all dependencies, health check endpoints for container orchestration, and CI/CD pipeline integration (render.yaml for deployment). The system is designed for containerized deployment with proper signal handling, graceful shutdown, and health monitoring. This enables easy deployment to Kubernetes, Docker Compose, or cloud platforms.

Provides a Selenium WebDriver compatibility layer that allows existing Selenium-based automation code to run against Steel Browser sessions, enabling gradual migration from Selenium to Steel Browser or hybrid workflows. The system implements WebDriver protocol endpoints that map to Steel Browser's CDP-based operations, providing a familiar API surface for Selenium users.

Manages proxy chains through ProxyFactory and proxy-chain modules, enabling IP rotation across multiple proxy servers and request-level filtering/interception via CDP's Network domain. The system can route browser traffic through configured proxies, intercept HTTP/HTTPS requests before they reach the target server, and filter or modify requests based on URL patterns or headers. This enables both IP anonymization for scraping and fine-grained control over which requests are allowed to execute.

Provides stateless, single-request operations for common web automation tasks (scrape, screenshot, PDF generation) through Quick Actions API endpoints that don't require session creation. The system automatically extracts structured content from pages using DOM parsing, handles JavaScript rendering, and returns results in a single HTTP response. This is optimized for simple, one-off operations where session persistence overhead is unnecessary.

Exposes a WebSocket API that streams real-time browser events (navigation, console logs, network requests, DOM mutations) and session state changes to connected clients. The system uses a WebSocket server plugin that subscribes to CDP events and broadcasts them to multiple concurrent clients, enabling live monitoring and debugging of browser automation sessions. This is essential for agents that need to react to page state changes or for developers debugging automation workflows.

Manages file operations (upload, download, archive creation) within browser sessions through the FileService module, enabling agents to interact with file inputs and capture downloaded files. The system intercepts download requests via CDP Network interception, stores files in session-scoped directories, and provides APIs to retrieve or archive downloaded content. This is critical for automating workflows that involve file handling (form submissions with attachments, downloading reports, etc.).

Enables loading and execution of Chrome extensions within automated browser sessions via CDP extension APIs, allowing agents to extend browser functionality with custom scripts, content scripts, and background workers. Extensions are loaded at session initialization and have full access to the page context, enabling use cases like ad blocking, analytics injection, or custom automation helpers. The system manages extension lifecycle and provides APIs to communicate with extension background scripts.

Provides a plugin architecture through BasePlugin abstract class and PluginManager that allows developers to extend Steel Browser functionality with custom plugins. Plugins can hook into session lifecycle events (creation, destruction), request/response cycles, and WebSocket communication. The system includes built-in plugins for WebSocket streaming, logging, and monitoring, and developers can create custom plugins by extending BasePlugin and registering with PluginManager.

Captures comprehensive browser events (navigation, console logs, network requests, performance metrics) through BrowserLogger and stores them in DuckDB (duckdb-async) for efficient querying and analysis. The system instruments the browser at the CDP level to capture all relevant events, persists them to a local database, and provides query APIs for retrieving event history. This enables post-session analysis, debugging, and performance monitoring of automation workflows.

Manages session configuration and state persistence through SessionService and ChromeContextService, enabling browser context (cookies, local storage, session storage, IndexedDB) to survive across multiple API requests. Sessions are identified by unique IDs and stored in a configurable storage backend, with support for session cloning, restoration, and cleanup. The system maintains a mapping between session IDs and Chrome DevTools Protocol contexts, enabling stateful automation workflows.