# Steel

Cloud browser sessions

- Package: @bijectionhq/steel
- Category: Web & Search
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/steel/tree/e36afeb17503b3f82f561bd197e7ed398f03f28d
- Upstream: https://github.com/steel-dev/steel-convex/tree/10f642fe9527c89fe7523f2a3c71bed5d0737bfa
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/steel

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/steel.git
cd steel
git checkout e36afeb17503b3f82f561bd197e7ed398f03f28d
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @steel-dev/convex; check the Bijection adaptation separately.

Steel Browser provides cloud browser automation for Convex applications with built-in multi-tenant session management. Run browser sessions in the cloud for web scraping, taking screenshots, solving captchas, and handling file operations directly from Convex actions. Sessions persist state in your Convex database with real-time queries and automatic tenant isolation by ownerId.

### Use cases

• **E-commerce monitoring** — Create persistent browser sessions to monitor competitor prices, track inventory changes, or scrape product data with session state stored in Convex for real-time frontend updates
• **Multi-tenant web automation** — Build SaaS applications where each customer gets isolated browser sessions for automated workflows, form submissions, or data collection without cross-tenant data leaks
• **Captcha-protected scraping** — Access websites that require captcha solving or complex authentication flows using persistent browser profiles and credential management
• **Document generation workflows** — Generate PDFs or screenshots of web pages as part of automated reporting pipelines with file management integrated into your Convex backend
• **Session-based testing** — Run browser-based integration tests or user journey validation with persistent sessions that maintain login state and browser profiles

### How it works

The component bridges Steel's cloud browser API with Convex's database and action system. You mount the component in `convex.config.ts`, then create a `SteelComponent` instance in your Convex actions with your API key. The component provides modules like `sessions`, `steel`, `captchas`, and `files` that wrap Steel API calls while persisting state in your Convex database.

Every operation accepts an `ownerId` parameter that provides automatic multi-tenant isolation at the database level. When you call `steel.sessions.create()` or `steel.steel.scrape()`, the component makes the Steel API request and stores session metadata in Convex tables. Your frontend can then query session state in real-time using standard Convex queries without polling.

The `sessions` module manages full browser lifecycle with methods like `create()`, `refresh()`, and `release()`. The `steel` module provides one-shot operations for scraping, screenshots, and PDF generation without session management. Additional modules handle captcha solving, browser profiles, credentials, extensions, and file operations, all scoped by tenant and queryable from your Convex functions.

### Upstream README

# Steel Convex Component

A [Convex](https://convex.dev) component for [Steel](https://steel.dev) cloud browser sessions. Manage browser sessions, scrape pages, solve captchas, and handle files — all from your Convex actions, with built-in multi-tenant isolation.

Features:

- **Multi-tenant sessions** — Every operation is scoped by `ownerId`. Tenant A never sees Tenant B's sessions.
- **Full session lifecycle** — Create, refresh, release, bulk-refresh, and bulk-release browser sessions.
- **Scraping & screenshots** — Scrape a page, take a screenshot, or generate a PDF in a single call.
- **Captcha solving** — Check captcha status, solve text captchas, or solve image captchas on any session.
- **Profiles & credentials** — Persist browser profiles and saved logins across sessions.
- **Extensions & files** — Upload browser extensions, attach files to sessions, or manage global files.
- **Convex-native state** — Session state is persisted in your Convex database, queryable in real time from your frontend.

## Quick Start

### 1. Install

```bash
npm install @steel-dev/convex convex
```

### 2. Mount the component

In your `convex/convex.config.ts`:

```ts
import { defineApp } from "convex/server";
import steel from "@steel-dev/convex/convex.config";

const app = defineApp();
app.use(steel);
export default app;
```

### 3. Set your API key

```bash
npx convex env set STEEL_API_KEY <your_steel_key>
```

### 4. Create your first session

In a Convex action file, e.g. `convex/steelActions.ts`:

```ts
import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { SteelComponent } from "@steel-dev/convex";

const steel = new SteelComponent(components.steel, {
  STEEL_API_KEY: process.env.STEEL_API_KEY,
});

export const createSession = action({
  args: {},
  handler: async (ctx) =>
    steel.sessions.create(
      ctx,
      { sessionArgs: { timeout: 120000 } },
      { ownerId: "tenant-a" },
    ),
});
```

### 5. Run it

```bash
npx convex dev
npx convex run steelActions:createSession
```

## Modules

| Module | What it does |
|---|---|
| `sessions` | Create, refresh, release, list, and inspect browser sessions |
| `steel` | One-shot scrape, screenshot, or PDF — no session management needed |
| `captchas` | Check status, solve text captchas, solve image captchas |
| `profiles` | Create, update, list, and retrieve browser profiles |
| `credentials` | Store and manage saved login credentials |
| `extensions` | Upload, update, delete, and download browser extensions |
| `files` | Upload, download, and delete global files |
| `sessionFiles` | Attach, list, and delete files on individual sessions |

## How it works

Steel handles the cloud browser. Convex handles the state. This component bridges both:

1. Your Convex action calls the Steel API to create or manage a browser session.
2. The component persists session state in your Convex database.
3. Your frontend can query session data in real time — no polling, no webhooks.

All operations are scoped by `ownerId`, so multi-tenant isolation is built in at the data layer.

## Constructor options

```ts
const steel = new SteelComponent(components.steel, {
  STEEL_API_KEY: process.env.STEEL_API_KEY,  // API key (or set via env var)
  ownerId: "default-tenant",                  // Default ownerId for all calls
});
```

- `STEEL_API_KEY` — Your Steel API key. If omitted, falls back to `process.env.STEEL_API_KEY`.
- `ownerId` — Default owner for all method calls. Can be overridden per call via the options argument.

## Troubleshooting

**`Missing STEEL_API_KEY`** — The Convex runtime does not inherit your shell environment. Set it explicitly:

```bash
npx convex env set STEEL_API_KEY <your_key>
```

**`Schema file missing default export`** — Make sure `convex/schema.ts` uses `export default defineSchema({...})`, not a named export.

**`No matching export ... components`** — Import `components` from `./_generated/api`, not `./_generated/server`.

**`paginate() is only supported in the app`** — This is a known Convex limitation. The component uses `take()` internally instead of `paginate()`.

## Guides & Reference

- [Getting Started Guide](./GUIDE.md) — step-by-step walkthrough with a real-world price monitor example
- [API Reference](./API.md) — full method signatures for every module
- [Demo project](https://github.com/steel-experiments/steel-convex-demo) — working example app

## Development

```bash
npm run codegen:verify
npm run typecheck
npm run test
npm run build
```

`npm run codegen:verify` and `npm test` start a local anonymous Convex backend automatically, so they do not require a cloud `CONVEX_DEPLOYMENT` or deploy key in CI.

Live integration smoke test (requires a Steel API key):

```bash
STEEL_API_KEY=... STEEL_LIVE_TEST=1 npm test
```

## License

MIT