
npm install browser-use-convex-componentA Convex component that wraps the Browser Use Cloud API, enabling AI-powered browser automation with persistent task tracking, session management, and reactive queries.
npm install browser-use-convex-componentIn 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;Set the BROWSER_USE_API_KEY environment variable in your Convex deployment:
npx convex env set BROWSER_USE_API_KEY bu_your_api_key_hereimport { BrowserUse } from "browser-use-convex-component";
import { components } from "./_generated/api.js";
const browserUse = new BrowserUse(components.browserUse);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 };
},
});export const listTasks = query({
args: {},
returns: v.any(),
handler: async (ctx) => {
return await browserUse.listTasks(ctx);
},
});export const checkTask = action({
args: { externalId: v.string() },
returns: v.any(),
handler: async (ctx, args) => {
return await browserUse.fetchTaskStatus(ctx, args);
},
});export const createSession = action({
args: {},
returns: v.any(),
handler: async (ctx) => {
return await browserUse.createSession(ctx, {
proxyCountryCode: "us",
});
},
});export const listProfiles = action({
args: {},
returns: v.any(),
handler: async (ctx) => {
return await browserUse.listProfiles(ctx);
},
});| 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 |
| 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 |
| 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 |
| 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 |
MIT