Browser Automation | Modbox

Modbox browser sandboxes run a full Chromium instance with a VNC display and Chrome DevTools Protocol (CDP) endpoint exposed over HTTPS. You can connect any automation library — Playwright, Puppeteer, or an AI browser agent — to the sandbox URL.

Use cases

🤖 AI browser agents — Connect an LLM to a live browser (like Browser Use or OpenAI’s CUA)
🔍 Web scraping — Run authenticated scraping jobs in isolated containers
🧪 E2E testing — Spin up fresh browsers for parallel test runs
📸 Screenshot / PDF generation — Render pages headlessly and export

How it works

A Modbox browser sandbox exposes:

CDP endpoint at wss://your-sandbox.modbox.run/cdp — connect Playwright, Puppeteer, or any CDP client
VNC viewer at https://your-sandbox.modbox.run — watch the browser in real time via your browser

Example: Playwright with a Modbox sandbox

1 import { chromium } from "playwright";
2 import { ModboxClient } from "modbox-sdk";
3 
4 const modbox = new ModboxClient({ token: process.env.MODBOX_API_TOKEN });
5 
6 async function scrapeWithSandbox(url: string) {
7   const taskId = `scrape-${Date.now()}`;
8 
9   // 1. Provision the browser sandbox
10   await modbox.provisionSandbox({
11     taskId,
12     imageId: process.env.BROWSER_IMAGE_ID, // Modbox Chromium image
13     ttlSeconds: 300,
14   });
15 
16   await modbox.waitForSandbox({ taskId, timeout: 60 });
17   const sandbox = await modbox.getSandbox(taskId);
18 
19   // 2. Connect Playwright to the sandbox CDP endpoint
20   const browser = await chromium.connectOverCDP(
21     `wss://${new URL(sandbox.sandboxUrl).host}/cdp`
22   );
23 
24   const page = await browser.newPage();
25 
26   // 3. Do your automation
27   await page.goto(url);
28   const title = await page.title();
29   const content = await page.content();
30 
31   await browser.close();
32 
33   // 4. Clean up
34   await modbox.destroySandbox({ taskId });
35 
36   return { title, content };
37 }

Example: AI browser agent

Connect an LLM-powered agent to a live Chromium sandbox:

1 import { ModboxClient } from "modbox-sdk";
2 import { Agent } from "browser-use"; // or your preferred AI browser agent
3 
4 const modbox = new ModboxClient({ token: process.env.MODBOX_API_TOKEN });
5 
6 async function runBrowserAgent(task: string) {
7   const taskId = `browser-agent-${Date.now()}`;
8 
9   await modbox.provisionSandbox({
10     taskId,
11     imageId: process.env.BROWSER_IMAGE_ID,
12     ttlSeconds: 900, // 15 minutes for complex tasks
13   });
14 
15   await modbox.waitForSandbox({ taskId, timeout: 60 });
16   const sandbox = await modbox.getSandbox(taskId);
17 
18   // Connect the AI agent to the live browser
19   const agent = new Agent({
20     task,
21     cdpUrl: `wss://${new URL(sandbox.sandboxUrl).host}/cdp`,
22     llm: yourLLMClient,
23   });
24 
25   const result = await agent.run();
26 
27   await modbox.destroySandbox({ taskId });
28   return result;
29 }

Parallel browser jobs

Provision multiple sandboxes in parallel for high-throughput scraping or test runs:

1 const urls = ["https://example.com", "https://example.org", "https://example.net"];
2 
3 // Provision all sandboxes in parallel
4 const sandboxes = await Promise.all(
5   urls.map((url, i) =>
6     modbox.provisionSandbox({ taskId: `scrape-${i}`, ttlSeconds: 120 })
7   )
8 );
9 
10 // Wait for all to be ready
11 await Promise.all(
12   sandboxes.map((s) => modbox.waitForSandbox({ taskId: s.taskId }))
13 );
14 
15 // Run scraping jobs in parallel
16 const results = await Promise.all(
17   sandboxes.map((s, i) => scrapeUrl(s.sandboxUrl, urls[i]))
18 );