## 1. Project Overview & Quickstart (steel-dev/steel-browser)

## File: README.md

<h3 align="center">**Steel**</h3>




<h4 align="center">
    <a href="https://app.steel.dev/sign-up" target="_blank">
      Get Started
  </a>  ·
    <a href="https://docs.steel.dev/" target="_blank">
      Documentation
  </a>  ·
  <a href="https://steel.dev/" target="_blank">
      Website
  </a> ·
  <a href="https://github.com/steel-dev/steel-cookbook" target="_blank">
      Cookbook
  </a>
</h4>



## ✨ Highlights

[Steel.dev](https://steel.dev) is an open-source browser API that makes it easy to build AI apps and agents that interact with the web. Instead of building automation infrastructure from scratch, you can focus on your AI application while Steel handles the complexity.

Under the hood, it manages sessions, pages, and browser processes, allowing you to perform complex browsing tasks programmatically without any of the headaches:
- **Full Browser Control**: Uses Puppeteer and CDP for complete control over Chrome instances -- allowing you to connect using Puppeteer, Playwright, or Selenium.
- **Session Management**: Maintains browser state, cookies, and local storage across requests
- **Proxy Support**: Built-in proxy chain management for IP rotation
- **Extension Support**: Load custom Chrome extensions for enhanced functionality
- **Debugging Tools**: Built-in request logging and a UI to view/debug sessions with
- **Anti-Detection**: Includes stealth plugins and fingerprint management
- **Resource Management**: Automatic cleanup and browser lifecycle management
- **Browser Tools**: Exposes APIs to quick convert pages to markdown, readability, screenshots, or PDFs.


For detailed API documentation and examples, check out our [API reference](https://docs.steel.dev/api-reference) or explore the Swagger UI directly at `http://0.0.0.0:3000/documentation`.

> Steel is in public beta and evolving every day. Your suggestions, ideas, and reported bugs help us immensely. Do not hesitate to join in the conversation on [Discord](https://discord.gg/steel-dev) or raise a GitHub issue. We read everything, respond to most, and love you.

If you love open-source, AI, and dev tools, [we're hiring across the stack](https://jobs.ashbyhq.com/steel)!

### Make sure to give us a star ⭐



## 🛠️ Getting Started
The easiest way to get started with Steel is by creating a [Steel Cloud](https://app.steel.dev) account. Otherwise, you can deploy this Steel browser instance to a cloud provider or run it locally.

## ⚡ Quick Deploy
If you're looking to deploy to a cloud provider, we've got you covered.

| Deployment methods | Link |
| -------------------- | ----- |
| Pre-built Docker Image (combined API + UI) | [](https://github.com/steel-dev/steel-browser/pkgs/container/steel-browser) |
| 1-click deploy to Railway | [](https://railway.app/deploy/steelbrowser) |
| 1-click deploy to Render | [](https://render.com/deploy) |


## 💻 Running Locally

### Docker

The simplest way to deploy/run a Steel browser instance locally is to run the pre-built Docker image:

```bash
# Pull and run the Docker image
docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser
```

This will start the Steel browser server on port 3000 (http://localhost:3000) and the UI at http://localhost:3000/ui. The 9223 port is used for the console debugger.

You can now create sessions, scrape pages, take screenshots, and more. Jump to the [Usage](#usage) section for some quick examples on how you can do that.

Alternatively, you can run the API and UI separately with docker compose:

```bash
docker compose up
```

For Mac Silicon users, you will need to pass this env flag to the Docker compose command to run the images on the correct platform:
```bash
DOCKER_DEFAULT_PLATFORM=linux/arm64 docker compose up
```

## Quickstart for Contributors
When developing locally, you will need to run the [`docker-compose.dev.yml`](./docker-compose.dev.yml) file instead of the default [`docker-compose.yml`](./docker-compose.yml) file so that your local changes are reflected. Doing this will build the Docker images from the [`api`](./api) and [`ui`](./ui) directories and run the server and UI on port 3000 and 5173 respectively.

```bash
docker compose -f docker-compose.dev.yml up
```

You will also need to run it with `--build` to ensure the Docker images are re-built every time you make changes:

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

If you run on a custom host, create a `.env` file (see `docs/DEVELOPMENT_SETUP.md` for variables) or modify the environment variables used by `docker-compose.dev.yml` to use your host.

### Node.js
Alternatively, if you have Node.js and Chrome installed, you can run both the server and the UI directly:

```bash
npm install
npm run dev
```

This will also start the Steel server on port 3000 and the UI on port 5173.

Make sure you have the Chrome executable installed and in one of these 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 Executable

If you have a custom Chrome executable or a different path, you can set the `CHROME_EXECUTABLE_PATH` environment variable to the path of your Chrome executable:

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

For more details on where this is checked look at [`api/src/utils/browser.ts`](./api/src/utils/browser.ts).

## 🏄🏽‍♂️ Usage
> If you're looking for quick examples on how to use Steel, check out the [Cookbook](https://github.com/steel-dev/steel-cookbook).
>
> Alternatively you can play with the [REPL package](./repl/README.md) too `cd repl` and `npm run start`

There are two main ways to interact with the Steel browser API:
1. [Using Sessions](#sessions)
2. [Using the Quick Actions Endpoints](#quick-actions-api)

In these examples, we assume your custom Steel API endpoint is `http://localhost:3000`.

The full REST OpenAPI documentation can be found [on our site](https://docs.steel.dev/api-reference) and on your local Steel instance at `http://localhost:3000/documentation`.

#### Using the SDKs
If you prefer to use the our Python and Node SDKs, you can install the `steel-sdk` package for Node or Python.

These SDKs are built on top of the REST API and provide a more convenient way to interact with the Steel browser API. They are fully typed, and are compatible with both Steel Cloud and self-hosted Steel instances (changeable using the `baseURL` option on Node and `base_url` on Python).

For more details on installing and using the SDKs, please see the [Node SDK Reference](https://github.com/steel-dev/steel-node/blob/main/api.md) and the [Python SDK Reference](https://github.com/steel-dev/steel-python/blob/main/api.md).


### Sessions
The `/sessions` endpoint lets you relaunch the browser with custom options or extensions (e.g. with a custom proxy) and also reset the browser state. Perfect for complex, stateful workflows that need fine-grained control.

Once you have a session, you can use the session ID or the root URL to interact with the browser. To do this, you will need to use Puppeteer or Playwright. You can find some examples of how to use Puppeteer and Playwright with Steel in the docs below:
* [Puppeteer Integration](https://docs.steel.dev/overview/guides/puppeteer)
* [Playwright with Node](https://docs.steel.dev/overview/guides/playwright-node)
* [Playwright with Python](https://docs.steel.dev/overview/guides/playwright-python)


**Creating a Session using the Node SDK**


```typescript
import Steel from 'steel-sdk';

const client = new Steel({
  baseURL: "http://localhost:3000", // Custom API Base URL override
});

(async () => {
  try {
    // Create a new browser session with current API fields
    const session = await client.sessions.create({
      blockAds: true,
      proxyUrl: "user:pass@host:port", // optional
      dimensions: { width: 1280, height: 800 }, // optional
    });
    console.log("Created session with ID:", session.id);
  } catch (error) {
    console.error("Error creating session:", error);
  }
})();
````



**Creating a Session using the Python SDK**


````python
import os
from steel import Steel

client = Steel(
    base_url="http://localhost:3000",  # Custom API Base URL override
)

try:
    # Create a new browser session with custom options
    session = client.sessions.create(
        block_ads=True,
        proxy_url="user:pass@host:port",  # optional
        dimensions={"width": 1280, "height": 800},  # optional
    )
    print("Created session with ID:", session.id)
except Exception as e:
    print("Error creating session:", e)
````



**Creating a Session using Curl**


```bash
# Launch a new browser session
curl -X POST http://localhost:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "proxyUrl": "user:pass@host:port",
    "blockAds": true,
    "dimensions": { "width": 1280, "height": 800 }
  }'
```



#### Selenium Sessions
>**Note:** This integration does not support all the features of the CDP-based browser sessions API.

For teams with existing Selenium workflows, the Steel browser provides a drop-in replacement that adds enhanced features while maintaining compatibility. You can simply use the `isSelenium` option to create a Selenium session:

```typescript
// Using the Node SDK
const session = await client.sessions.create({ isSelenium: true });
```
```python
# Using the Python SDK
session = client.sessions.create(is_selenium=True)
```

**Using Curl**


```bash
# Launch a Selenium session
curl -X POST http://localhost:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "isSelenium": true
  }'
```



The Selenium API is fully compatible with Selenium's WebDriver protocol, so you can use any existing Selenium clients to connect to the Steel browser. **For more details on using Selenium with Steel, refer to the [Selenium Docs](https://docs.steel.dev/overview/guides/selenium).**

### Quick Actions API
The `/scrape`, `/screenshot`, and `/pdf` endpoints let you quickly extract clean, well-formatted data from any webpage using the running Steel server. Ideal for simple, read-only, on-demand jobs:


**Scrape a Web Page**


Extract the HTML content of a web page.

```bash
# Example using the Actions API
curl -X POST http://0.0.0.0:3000/v1/scrape \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "delay": 1000
  }'
```



**Take a Screenshot**


Take a screenshot of a web page.
```bash
# Example using the Actions API
curl -X POST http://0.0.0.0:3000/v1/screenshot \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "fullPage": true
  }' --output screenshot.png
```



**Download a PDF**


Download a PDF of a web page.
```bash
# Example using the Actions API
curl -X POST http://0.0.0.0:3000/v1/pdf \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }' --output output.pdf
```


## Get involved
Steel browser is an open-source project, and we welcome contributions!
- Questions/ideas/feedback? Come hangout on [Discord](https://discord.gg/steel-dev)
- Found a bug? Open an issue on [GitHub](https://github.com/steel-dev/steel-browser/issues)

## License
[Apache 2.0](./LICENSE)

---

Made with ❤️ by the Steel team.

---

## File: docs/README.md

# Steel Browser Documentation

Welcome to the Steel Browser documentation! This directory contains comprehensive guides and references to help you understand, use, and contribute to Steel Browser.

## 📚 Documentation Overview

### Getting Started

- **[Development Setup Guide](DEVELOPMENT_SETUP.md)** - Complete setup instructions for development environment
- **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute to the project
- **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Common issues and solutions

### Architecture & Design

- **[Architecture Overview](ARCHITECTURE.md)** - System design and component relationships
- **[Plugin Development Guide](PLUGIN_DEVELOPMENT.md)** - Creating custom plugins

### API Reference

- **[API Documentation](http://localhost:3000/documentation)** - Interactive API reference (when running locally)
- **[OpenAPI Schema](../api/openapi/schemas.json)** - Machine-readable API specification

## 🚀 Quick Links

### For New Contributors

1. Start with the [Contributing Guide](../CONTRIBUTING.md)
2. Set up your development environment using the [Development Setup Guide](DEVELOPMENT_SETUP.md)
3. Read the [Architecture Overview](ARCHITECTURE.md) to understand the system
4. Check out issues labeled [`good first issue`](https://github.com/steel-dev/steel-browser/labels/good%20first%20issue)

### For Plugin Developers

1. Read the [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
2. Study the [Architecture Overview](ARCHITECTURE.md) for system understanding
3. Browse existing plugins in `api/src/services/cdp/plugins/`
4. Join our [Discord](https://discord.gg/steel-dev) for plugin development discussions

### For Users

1. Check the main [README](../README.md) for basic usage
2. Browse the [Steel Cookbook](https://github.com/steel-dev/steel-cookbook) for examples
3. Use the [Troubleshooting Guide](TROUBLESHOOTING.md) if you encounter issues
4. Visit the [API Documentation](http://localhost:3000/documentation) for detailed API reference

## 🛠️ Documentation Structure

```
docs/
├── README.md                  # This file - documentation overview
├── ARCHITECTURE.md           # System architecture and design
├── DEVELOPMENT_SETUP.md      # Development environment setup
├── PLUGIN_DEVELOPMENT.md     # Plugin creation guide
└── TROUBLESHOOTING.md        # Common issues and solutions
```

## 📖 External Resources

### Official Resources

- **[Steel Browser Repository](https://github.com/steel-dev/steel-browser)** - Main repository
- **[Steel Cookbook](https://github.com/steel-dev/steel-cookbook)** - Usage examples and recipes
- **[Discord Community](https://discord.gg/steel-dev)** - Real-time support and discussions
- **[Official Documentation](https://docs.steel.dev/)** - Comprehensive online docs

### Learning Resources

- **[Puppeteer Documentation](https://pptr.dev/)** - Browser automation library
- **[Fastify Documentation](https://www.fastify.io/)** - Web framework used in API
- **[React Documentation](https://react.dev/)** - Frontend framework
- **[TypeScript Handbook](https://www.typescriptlang.org/docs/)** - TypeScript language guide

## 🤝 Contributing to Documentation

We welcome contributions to improve our documentation! Here's how you can help:

### Reporting Documentation Issues

- **Missing Information**: If you can't find what you're looking for
- **Outdated Content**: If documentation doesn't match current behavior
- **Unclear Instructions**: If steps are confusing or incomplete
- **Broken Links**: If links don't work or point to wrong resources

### Improving Documentation

1. **Fork the repository** and create a feature branch
2. **Make your changes** to the relevant documentation files
3. **Test your changes** by following the instructions you've written
4. **Submit a pull request** with a clear description of improvements

### Documentation Standards

- **Use clear, concise language** that's accessible to all skill levels
- **Include code examples** where applicable
- **Add screenshots** for UI-related documentation
- **Keep examples up-to-date** with current API and features
- **Cross-reference related sections** to help users navigate

## 🔍 Finding What You Need

### By Use Case

**I want to...**

- **Use Steel Browser** → Start with the main [README](../README.md)
- **Contribute code** → Read the [Contributing Guide](../CONTRIBUTING.md)
- **Set up development** → Follow the [Development Setup Guide](DEVELOPMENT_SETUP.md)
- **Create a plugin** → Study the [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
- **Understand the system** → Read the [Architecture Overview](ARCHITECTURE.md)
- **Fix an issue** → Check the [Troubleshooting Guide](TROUBLESHOOTING.md)

### By Component

**I'm working with...**

- **API/Backend** → [Architecture](ARCHITECTURE.md) + [API Docs](http://localhost:3000/documentation)
- **Frontend/UI** → [Architecture](ARCHITECTURE.md) + UI source code
- **Plugins** → [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
- **Docker** → [Development Setup](DEVELOPMENT_SETUP.md) + [Troubleshooting](TROUBLESHOOTING.md)

## 📋 Documentation Roadmap

### Planned Additions

- **Deployment Guide** - Production deployment instructions
- **Security Guide** - Security best practices and configuration
- **Performance Guide** - Optimization and scaling recommendations
- **Testing Guide** - Comprehensive testing strategies
- **Migration Guide** - Upgrading between versions
- **FAQ** - Frequently asked questions

### Community Contributions Needed

- **Platform-specific guides** (Windows, macOS, Linux variations)
- **Integration examples** with popular tools and frameworks
- **Video tutorials** for complex setup procedures
- **Translated documentation** for non-English speakers
- **Real-world use case studies**

## 💡 Getting Help

If you can't find what you're looking for in the documentation:

1. **Search existing issues** on GitHub
2. **Ask in Discord** for real-time help
3. **Create a documentation issue** describing what's missing
4. **Check the [Steel Cookbook](https://github.com/steel-dev/steel-cookbook)** for practical examples

## 🎯 Documentation Goals

Our documentation aims to be:

- **Comprehensive** - Covering all aspects of Steel Browser
- **Accessible** - Understandable by users of all skill levels
- **Up-to-date** - Reflecting the current state of the project
- **Practical** - Including real-world examples and use cases
- **Community-driven** - Improved through user feedback and contributions

---

**Happy learning and building with Steel Browser!** 🚀

*Last updated: [Current Date] - If you notice outdated information, please let us know!*

## 2. Official Technical Reference & Guides (steel-dev/docs)

# Steel Docs

Documentation for Steel.dev. Built with [Fumadocs](https://fumadocs.vercel.app/) and enhanced with custom components.

## Contributing

### Documentation Structure

**Component-Based** (`/tools/*`): Features organized by tool capabilities

Example structure:

```
/tools/steel/
├── Overview/                 # Introduction and setup
├── Steel CLI/             # Command-line features
├── Steel JS SDK/          # Testing and programmatic usage
└── Integrations/             # External connections
```

### Writing Guidelines

After installing dependencies, install [Vale](https://vale.sh/docs/install), sync the pinned style
packages, and run the prose checks before submitting documentation changes:

```bash
brew install vale
bun add --global mdx2vast@0.5.0
bun run prose:sync
bun run prose
```

Vale checks MDX-aware editorial and Steel terminology rules. `cspell` remains the source of truth
for spelling and project vocabulary. During the initial rollout, Vale reports warnings without
failing the command or CI.

Follow our content rhythm pattern:

```
Paragraph (2-3 sentences) → Code Example → Paragraph → List/Table → Code
```

- **60% code, 40% text** - Show, don't just tell
- **Never put two paragraphs in a row** - Break with code/lists/tables
- **Every concept needs a code example**
- **Use complete, contextual sentences** - Explain "why" before "how"

### Available Components

#### Layout Components

````mdx
<Steps>
  <Step>
    ### Action verb phrase Context sentence explaining what and why. ```terminal
    $ command with options ```
  </Step>
</Steps>

---

<TerminalPicker storage="macOs" flags="-w">

```terminal !! macOS
$ brew install @steel-dev/cli
```

```terminal !! Windows
$ winget install @steel-dev/cli
```

</TerminalPicker>

---

<CodeTabs storage="languageSwitcher">

```typescript
const client = Steel()
const result = await client.sessions.create()
```

```javascript
const client = Steel()
const result = await client.sessions.create()
```

</CodeTabs>
````

#### Directives (Auto-converted to components)


```mdx
:::callout
type: tip|info|warn|help
### Optional Title
Content here
:::

:::objectives
- What you'll learn
- Another learning objective
:::

:::prerequisites
- Required knowledge
- Tools needed
:::

:::next-steps
- [Next Guide](/path): Description
- [Another Guide](/path): Description
:::
```


#### Interactive Components

```mdx
<Accordion>
  <AccordionItem>
    <AccordionTrigger>Question</AccordionTrigger>
    <AccordionContent>Answer</AccordionContent>
  </AccordionItem>
</Accordion>


```

#### Code Block Features

**Languages**: `terminal`, `typescript`, `javascript`, `json`, `yaml`, `console`, `package-install`

**Flags**: `-n` (line numbers), `-c` (copy button), `-w` (word wrap), `-a` (animate), `-f <file-name>` (file name)

**Annotations**:

````mdx
```ts
// !mark[3:5]     Highlight lines 3-5
// !mark[/regex/] Highlight pattern
// !diff +        Addition
// !diff -        Removal
// !collapse[3:5] Collapse lines
```
````

````

**Special blocks**:

```terminal
$ command         # Renders with prompt
```

```package-install
@steel-dev/cli  # Auto-generates npm/yarn/pnpm commands
```

````

### Page Templates

#### Overview Page

```mdx
---
title: Tool Name
sidebarTitle: Overview
---

## Overview

Expand on what the tool does and its value. Include llms.txt link if available.

## Key features

- **Feature** - User benefit description
- **Feature** - Technical capability explained simply

## Installation

<TerminalPicker>...</TerminalPicker>

:::next-steps

- [Quickstart](/path): Get started in minutes
  :::
```

use the `isLink: true` in the front matter to add a link icon to the right of the navbar icon
use the `isSeperator: true` in the frontmatter to make a doc element look like a seperator (Bold/All caps and spaced out, good for special links)

#### Quickstart Page

```mdx
---
title: Quickstart
---

Brief intro paragraph about what you'll build.

:::objectives

- Learning objective 1
- Learning objective 2
  :::

:::prerequisites

- Prerequisites
  :::

## Quickstart

<Steps>[3-5 focused steps]</Steps>

:::next-steps

- [Next Guide](/path): Description
  :::
```

### File Structure

- `/content/docs/` - All documentation content
- `/components/` - Custom components
- `/public/` - Images and static assets
- `meta.json` files control sidebar organization

### Quick Checklist

- Follow content rhythm (no consecutive paragraphs)
- 60% code, 40% text ratio
- Every concept has a code example
- Use appropriate page template
- Specify language for all code blocks
- Include context before code
- Keep paragraphs to 2-3 sentences