# Browser Use

A Bijection component for Browser Use Cloud - automate browser tasks with AI agents

- Package: @bijectionhq/browser-use
- Category: AI & Agents
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/browser-use/tree/8e37a347fe67379f6160844dd79b0f63ef87e7b2
- Upstream: https://github.com/Cheggin/browser-use-convex-component/tree/14bba13a1a7f7d22dad82369e8aec2600032f2ce
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/browser-use

## Get the source

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

```sh
git clone https://github.com/bijectionhq/browser-use.git
cd browser-use
git checkout 8e37a347fe67379f6160844dd79b0f63ef87e7b2
```

## 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 browser-use-convex-component; check the Bijection adaptation separately.

This component integrates Browser Use Cloud's AI-powered browser automation API with Convex's reactive database. It provides persistent task tracking, session management, and browser profile storage while enabling real-time queries on automation status. Developers get a full-stack solution for browser automation with reactive subscriptions to task progress and results.

### Use cases

- **Web scraping workflows** where you need to track long-running scraping tasks and reactively update your UI as data is collected
- **E2E testing automation** that requires persistent browser sessions across multiple test runs with profile-based authentication
- **User onboarding automation** where you guide users through complex web flows and need to monitor completion status in real-time
- **Content management tasks** like bulk social media posting or form submissions that benefit from visual element highlighting and structured output
- **Competitive analysis tools** that automate data collection from multiple domains with proxy rotation and session persistence

### How it works

The component wraps the Browser Use Cloud API in Convex actions while storing all task, session, and profile data in your Convex database. You initialize the `BrowserUse` client with your component's API surface, then call methods like `createTask()` to start browser automation jobs that persist their status locally.

Tasks support comprehensive configuration including AI model selection, structured JSON output schemas, domain restrictions, and custom secrets injection. The component provides both actions for API calls (like `fetchTaskStatus()`) and queries for reactive data access (like `listTasks()` and `getTaskSteps()`), enabling real-time UI updates as automation progresses.

Session and profile management enables persistent browser states across automation runs. Sessions can use proxy rotation and country-specific routing, while profiles store authentication cookies and browser preferences. All data flows through Convex's reactive system, so your frontend automatically updates when task status changes or new automation results arrive.

### Upstream README

# Browser Use Convex Component

A [Convex](https://convex.dev) component that wraps the [Browser Use Cloud API](https://cloud.browser-use.com), enabling AI-powered browser automation with persistent task tracking, session management, and reactive queries.

## Features

- **Task Management** - Create, monitor, and stop browser automation tasks
- **Session Management** - Create persistent browser sessions with proxy support
- **Profile Management** - Manage browser profiles for authentication persistence
- **Reactive Queries** - All task and session data stored in Convex for real-time subscriptions

## Installation

```bash
npm install browser-use-convex-component
```

## Setup

### 1. Configure your app

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

```typescript
import { defineApp } from "convex/server";
import browserUse from "browser-use-convex-component/convex.config.js";

const app = defineApp();
app.use(browserUse);

export default app;
```

### 2. Set your API key

Set the `BROWSER_USE_API_KEY` environment variable in your Convex deployment:

```bash
npx convex env set BROWSER_USE_API_KEY bu_your_api_key_here
```

## Usage

### Initialize the client

```typescript
import { BrowserUse } from "browser-use-convex-component";
import { components } from "./_generated/api.js";

const browserUse = new BrowserUse(components.browserUse);
```

### Create a task

```typescript
export const startTask = action({
  args: { task: v.string() },
  returns: v.any(),
  handler: async (ctx, args) => {
    const { taskId, externalId } = await browserUse.createTask(ctx, {
      task: args.task,
      startUrl: "https://example.com",
    });
    return { taskId, externalId };
  },
});
```

### Query tasks reactively

```typescript
export const listTasks = query({
  args: {},
  returns: v.any(),
  handler: async (ctx) => {
    return await browserUse.listTasks(ctx);
  },
});
```

### Check task status

```typescript
export const checkTask = action({
  args: { externalId: v.string() },
  returns: v.any(),
  handler: async (ctx, args) => {
    return await browserUse.fetchTaskStatus(ctx, args);
  },
});
```

### Session management

```typescript
export const createSession = action({
  args: {},
  returns: v.any(),
  handler: async (ctx) => {
    return await browserUse.createSession(ctx, {
      proxyCountryCode: "us",
    });
  },
});
```

### Profile management

```typescript
export const listProfiles = action({
  args: {},
  returns: v.any(),
  handler: async (ctx) => {
    return await browserUse.listProfiles(ctx);
  },
});
```

## API Reference

### Tasks

| Method | Type | Description |
|--------|------|-------------|
| `createTask(ctx, args)` | Action | Create a browser automation task |
| `getTask(ctx, { taskId })` | Query | Get task from local DB |
| `listTasks(ctx, opts?)` | Query | List tasks with optional filters |
| `getTaskSteps(ctx, { taskId })` | Query | Get step-by-step execution details |
| `fetchTaskStatus(ctx, { externalId })` | Action | Fetch latest status from API |
| `fetchTaskDetail(ctx, { externalId })` | Action | Fetch full details and steps from API |
| `stopTask(ctx, { externalId })` | Action | Stop a running task |

### Sessions

| Method | Type | Description |
|--------|------|-------------|
| `createSession(ctx, args?)` | Action | Create a browser session |
| `getSession(ctx, { sessionId })` | Query | Get session from local DB |
| `listSessions(ctx, opts?)` | Query | List sessions with optional filters |
| `fetchSessionDetail(ctx, { externalId })` | Action | Fetch session details from API |
| `stopSession(ctx, { externalId })` | Action | Stop a session |

### Profiles

| Method | Type | Description |
|--------|------|-------------|
| `createProfile(ctx, args?)` | Action | Create a browser profile |
| `listProfiles(ctx)` | Action | List all profiles |
| `getProfile(ctx, { profileId })` | Action | Get profile details |
| `updateProfile(ctx, { profileId, name })` | Action | Update profile name |
| `deleteProfile(ctx, { profileId })` | Action | Delete a profile |

## Task Options

| Option | Type | Description |
|--------|------|-------------|
| `task` | `string` | The instruction for the AI agent (required) |
| `llm` | `string` | AI model (default: `browser-use-2.0`) |
| `sessionId` | `string` | Existing session to use |
| `startUrl` | `string` | Initial URL to navigate to |
| `maxSteps` | `number` | Max execution steps (default: 100) |
| `flashMode` | `boolean` | Accelerated execution mode |
| `thinking` | `boolean` | Extended reasoning |
| `vision` | `boolean \| "auto"` | Visual recognition |
| `highlightElements` | `boolean` | Highlight interactive elements |
| `systemPromptExtension` | `string` | Append to the system prompt |
| `structuredOutput` | `object` | JSON schema for response formatting |
| `secrets` | `object` | Secure key-value data injection |
| `allowedDomains` | `string[]` | Navigation restrictions |
| `metadata` | `object` | Custom tracking pairs |
| `judge` | `boolean` | AI-powered success validation |
| `judgeGroundTruth` | `string` | Ground truth for judge evaluation |
| `judgeLlm` | `string` | Model for judge evaluation |
| `skillIds` | `string[]` | Pre-built skill IDs to use |

## License

MIT