RealtimeKeep your app up to date
AuthenticationOver 80+ OAuth integrations
Convex Components
ComponentsIndependent, modular, TypeScript building blocks for your backend.
Open sourceSelf host and develop locally
AI CodingGenerate high quality Convex code with AI
Compare
Convex vs. Firebase
Convex vs. Supabase
Convex vs. SQL
DocumentationGet started with your favorite frameworks
SearchSearch across Docs, Stack, and Discord
TemplatesUse a recipe to get started quickly
Convex ChampionsAmbassadors that support our thriving community
Convex for StartupsStart and scale your company with Convex
Convex for Open SourceSupport for open source projects
Convex for ClawSupport for projects in the OpenClaw ecosystem
Convex CommunityShare ideas and ask for help in our community Discord
Stack
Stack

Stack is the Convex developer portal and blog, sharing bright ideas and techniques for building with Convex.

Explore Stack
BlogDocsPricing
GitHub
Log inStart building
Back to Components

Browser Use

Cheggin's avatar
Cheggin/browser-use-convex-component
View repo
GitHub logoView package

Category

AI
Browser Use hero image
npm install 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#

MethodTypeDescription
createTask(ctx, args)ActionCreate a browser automation task
getTask(ctx, { taskId })QueryGet task from local DB
listTasks(ctx, opts?)QueryList tasks with optional filters
getTaskSteps(ctx, { taskId })QueryGet step-by-step execution details
fetchTaskStatus(ctx, { externalId })ActionFetch latest status from API
fetchTaskDetail(ctx, { externalId })ActionFetch full details and steps from API
stopTask(ctx, { externalId })ActionStop a running task

Sessions#

MethodTypeDescription
createSession(ctx, args?)ActionCreate a browser session
getSession(ctx, { sessionId })QueryGet session from local DB
listSessions(ctx, opts?)QueryList sessions with optional filters
fetchSessionDetail(ctx, { externalId })ActionFetch session details from API
stopSession(ctx, { externalId })ActionStop a session

Profiles#

MethodTypeDescription
createProfile(ctx, args?)ActionCreate a browser profile
listProfiles(ctx)ActionList all profiles
getProfile(ctx, { profileId })ActionGet profile details
updateProfile(ctx, { profileId, name })ActionUpdate profile name
deleteProfile(ctx, { profileId })ActionDelete a profile

Task Options#

OptionTypeDescription
taskstringThe instruction for the AI agent (required)
llmstringAI model (default: browser-use-2.0)
sessionIdstringExisting session to use
startUrlstringInitial URL to navigate to
maxStepsnumberMax execution steps (default: 100)
flashModebooleanAccelerated execution mode
thinkingbooleanExtended reasoning
visionboolean | "auto"Visual recognition
highlightElementsbooleanHighlight interactive elements
systemPromptExtensionstringAppend to the system prompt
structuredOutputobjectJSON schema for response formatting
secretsobjectSecure key-value data injection
allowedDomainsstring[]Navigation restrictions
metadataobjectCustom tracking pairs
judgebooleanAI-powered success validation
judgeGroundTruthstringGround truth for judge evaluation
judgeLlmstringModel for judge evaluation
skillIdsstring[]Pre-built skill IDs to use

License#

MIT

Get your app up and running in minutes
Start building
Convex logo
ProductSyncRealtimeAuthOpen sourceAI codingFAQChefMerchPricing
DevelopersDocsBlogComponentsTemplatesConvex for StartupsConvex for Open SourceConvex for ClawChampionsChangelogPodcastLLMs.txt
CompanyAbout usBrandInvestorsBecome a partnerJobsNewsEventsTerms of servicePrivacy policySecurity
SocialTwitterDiscordYouTubeLumaLinkedInGitHub
A Trusted Solution
  • SOC 2 Type II Compliant
  • HIPAA Compliant
  • GDPR Verified
©2026 Convex, Inc.