browser-use-convex-component

Browser Use Convex Component

A Convex component that wraps the Browser Use Cloud API, 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

npm install browser-use-convex-component

Setup

1. Configure your app

In your convex/convex.config.ts:

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:

npx convex env set BROWSER_USE_API_KEY bu_your_api_key_here

Usage

Initialize the client

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

const browserUse = new BrowserUse(components.browserUse);

Create a task

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

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

Check task status

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

Session management

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

Profile management

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