Steel Browser

Steel is an open-source browser API designed for AI agents and web automation. It manages the complexity of browser infrastructure, providing:

• Full Browser Control: Supports Puppeteer, Playwright, and Selenium via Puppeteer and CDP.
• Session Management: Maintains state, cookies, and local storage across requests.
• Proxy Support: Built-in proxy chain management for IP rotation.
• Extension Support: Ability to load custom Chrome extensions.
• Debugging Tools: Request logging and a UI for viewing/debugging sessions.
• Anti-Detection: Includes stealth plugins and fingerprint management.
• Resource Management: Automatic cleanup and lifecycle management.
• Browser Tools: APIs to convert pages to markdown, readability mode, screenshots, or PDFs.

You can run the API and UI separately using Docker Compose.

For Mac Silicon users, you must pass the DOCKER_DEFAULT_PLATFORM environment variable to ensure the images run on the correct platform:

docker compose up

# For Mac Silicon:
DOCKER_DEFAULT_PLATFORM=linux/arm64 docker compose up

Steel Browser uses structured logging via Pino. When implementing custom logic or monitoring, you can use the fastify.log object to emit structured logs. This allows for easier querying and observability by including relevant metadata like sessionId, action, and url alongside the log message.

fastify.log.info({ 
  sessionId, 
  action: 'page_created',
  url: page.url() 
}, 'New page created');

To get detailed execution information, enable verbose logging by setting the following environment variables:

• NODE_ENV=development
• ENABLE_VERBOSE_LOGGING=true
• ENABLE_CDP_LOGGING=true
• LOG_CUSTOM_EMIT_EVENTS=true

# Enable all debug logging
export NODE_ENV=development
export ENABLE_VERBOSE_LOGGING=true
export ENABLE_CDP_LOGGING=true
export LOG_CUSTOM_EMIT_EVENTS=true

# Start with debug logging
npm run dev -w api

If you have Node.js and Chrome installed, you can run the server and UI directly. This starts the Steel server on port 3000 and the UI on port 5173.

1. Install dependencies:

npm install

2. Run the development script:

npm run dev

Chrome Requirements: Ensure Chrome is installed in one of the following standard paths:

• Linux: /usr/bin/google-chrome
• MacOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe or C:\Program Files (x86)\Google\Chrome\Application\chrome.exe

Custom Chrome Path: If your Chrome executable is in a non-standard location, set the CHROME_EXECUTABLE_PATH environment variable:

export CHROME_EXECUTABLE_PATH=/path/to/your/chrome
npm run dev

Before setting up the development environment, ensure your system meets these requirements:

• OS: Linux, macOS, or Windows (WSL2 recommended).
• RAM: 8GB minimum (16GB+ recommended).
• Storage: 10GB+ free space.

Required Software

1. Node.js (Version 22+)

• Linux/macOS: Use nvm (recommended) or package managers (apt for Ubuntu/Debian, brew for macOS).
• Windows: Use choco or download from nodejs.org.

2. Git

• Install via apt/yum (Linux), brew (macOS), or choco (Windows).

3. Chrome/Chromium Browser

• Install google-chrome-stable or chromium-browser on Linux.
• Install google-chrome via Homebrew Cask on macOS.
• Install googlechrome via Chocolatey on Windows.

4. Docker (Optional but Recommended)

• Install via apt/yum (Linux), Homebrew Cask (macOS), or Chocolatey (Windows).

To begin using Steel Browser, refer to the main project README for basic usage instructions. For practical implementation examples and recipes, consult the Steel Cookbook.

If you encounter issues during use, refer to the Troubleshooting Guide.

Ensure your environment meets the following requirements:

• Node.js: version 22 or higher
• npm: installed and working
• Chrome/Chromium: installed and accessible
• Docker: installed (if using containers)

# Check Node.js version (should be 22+)
node --version

# Check npm version
npm --version

# Check Chrome/Chromium
google-chrome --version
# or
chromium --version

# Check Docker (if using containers)
docker --version
docker-compose --version

To set up a local development environment, follow the Development Setup Guide. This guide covers the complete setup required to build and run the project locally, including Docker configurations.

If you are working with the API/Backend, you should also review the Architecture Overview and access the interactive API Documentation (available when running locally).

To create custom plugins, follow these steps:

1. Read the Plugin Development Guide.
2. Study the Architecture Overview to understand the system design.
3. Browse existing plugin implementations located in api/src/services/cdp/plugins/ to use as a reference.
4. Join the Discord community for plugin development discussions.

For a containerized development environment, use Docker Compose:

Start environment:

docker-compose -f docker-compose.dev.yml up --build

Run in detached mode:

docker-compose -f docker-compose.dev.yml up -d --build

View logs:

docker-compose -f docker-compose.dev.yml logs -f