Browser-Use Custom: Build Your Own Agent Runtime

# Browser-Use Custom: Build Your Own Agent Runtime

The browser-use library made it easy to connect LLMs to a browser. But when you move from a local script to a production agent, you quickly hit the limits of a local Chrome instance. A browser-use custom setup requires a runtime that handles sessions, proxies, and debugging without you rebuilding infrastructure from scratch. This guide covers how to configure Remote Browser for your specific agent workloads, from CDP access to persistent profiles.

Why a Custom Runtime Matters

Most developers start with browser-use locally. It works for demos. Then you deploy an agent that needs to run for hours, access a specific site, or handle multiple concurrent tasks. Local browsers fail because they are tied to your machine's resources, IP address, and uptime.

A custom runtime decouples your agent logic from the browser execution environment. You define the browser behavior—session persistence, proxy settings, viewport, and automation protocol—while the runtime handles the actual Chromium instance. This separation is what allows you to scale from one script to a fleet of agents.

Remote Browser provides this layer. It exposes hosted Chromium sessions over CDP (Chrome DevTools Protocol) and is compatible with Playwright, Puppeteer, and Selenium. You keep your existing browser-use code, but you point it at a remote endpoint instead of a local browser.

Core Components of a Custom Setup

Before you write code, understand the building blocks you will configure.

1. Session Management

A session is a single browser instance. In a custom setup, you decide how long a session lives and whether it persists.

• Ephemeral sessions: Spin up for a single task, then destroy. Good for isolated, stateless operations.
• Persistent sessions: Maintain cookies, local storage, and profiles across multiple calls. Essential for logged-in workflows or tasks that span several steps.

Remote Browser lets you create both. Persistent profiles are stored server-side, so your agent can resume work exactly where it left off, even after a network disconnect.

2. CDP and Protocol Access

CDP is the foundation. It gives you fine-grained control over the browser—network interception, DOM manipulation, performance metrics, and more. If you are building a browser-use custom integration, you will likely want raw CDP access rather than just a high-level library wrapper.

Remote Browser exposes a CDP endpoint for each session. You can connect directly using a WebSocket or use a library like Playwright that speaks CDP under the hood.

3. Proxy and Network Configuration

Your agent's IP address often determines whether a site blocks it or serves the right content. A custom runtime lets you assign a proxy per session. This is critical for:

• Geo-specific testing
• Avoiding rate limits on shared IPs
• Accessing region-locked content

Remote Browser supports configurable proxy settings per session. You can route traffic through residential or datacenter proxies depending on your use case.

4. Stealth and Anti-Detection Settings

If your agent interacts with sites that employ bot detection, you need to control browser fingerprints. A custom setup allows you to adjust viewport, user agent, timezone, and other attributes that sites use for fingerprinting.

Remote Browser offers configurable browser settings for this purpose. You can set these per session or per profile, giving you consistent behavior across runs.

Configuring Remote Browser for Your Agent

Here is a practical walkthrough of setting up a custom session with Remote Browser using Playwright and CDP.

Step 1: Create a Session

First, you need a session ID. You can create one via the Remote Browser API or the dashboard. The API returns a WebSocket URL you can connect to.

curl -X POST https://api.remote-browser.dev/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "my-agent-profile",
    "proxy": "residential:us-east",
    "viewport": {"width": 1280, "height": 720}
  }'

The response includes a sessionId and a webSocketUrl.

Step 2: Connect with Playwright

Playwright can connect to an existing browser over CDP. Use the connectOverCDP method with the WebSocket URL.

import { chromium } from 'playwright';

async function runAgent() {
  // Connect to the remote Chromium session
  const browser = await chromium.connectOverCDP(
    'wss://api.remote-browser.dev/cdp/session_12345'
  );

  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  // Your agent logic here
  await page.goto('https://example.com');
  const title = await page.title();
  console.log(`Page title: ${title}`);

  // Don't close the browser if you want to reuse the session
  // await browser.close();
}

runAgent();

This code connects to a live session. If you use a persistent profile, the cookies and storage from previous runs are already loaded.

Step 3: Use Raw CDP for Advanced Control

Sometimes you need to send CDP commands directly. Playwright exposes a CDP session for this.

import { chromium } from 'playwright';

async function interceptNetwork() {
  const browser = await chromium.connectOverCDP(
    'wss://api.remote-browser.dev/cdp/session_12345'
  );
  const context = browser.contexts()[0];
  const page = context.pages()[0];

  const client = await context.newCDPSession(page);

  // Enable network interception
  await client.send('Network.enable');

  // Listen for responses
  client.on('Network.responseReceived', (event) => {
    console.log(`Response: ${event.response.status} for ${event.response.url}`);
  });

  await page.goto('https://example.com');
}

interceptNetwork();

This pattern is useful for debugging, logging, or modifying requests on the fly.

Comparison: Local vs. Hosted Custom Runtime

For a browser-use custom workflow, the hosted option removes the operational overhead. You focus on agent logic, not on keeping browsers alive.

Building a Custom Agent Loop

A common pattern is a loop where the agent:

1. Receives a task
2. Opens a browser session
3. Performs actions (click, type, navigate)
4. Extracts data
5. Returns results
6. Optionally keeps the session alive for follow-up tasks

Here is how that looks with Remote Browser.

import { chromium } from 'playwright';

async function agentLoop(task: string, sessionUrl: string) {
  const browser = await chromium.connectOverCDP(sessionUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  try {
    // Navigate to the starting point
    await page.goto('https://your-target-site.com');

    // Perform task-specific actions
    // This is where you'd integrate with an LLM to decide next steps
    const result = await page.evaluate(() => {
      // Extract data from the page
      return document.title;
    });

    console.log(`Task: ${task}`);
    console.log(`Result: ${result}`);

    return result;
  } catch (error) {
    console.error(`Agent failed: ${error.message}`);
    throw error;
  }
  // Note: We don't close the browser here to allow session reuse
}

// Usage
const sessionUrl = 'wss://api.remote-browser.dev/cdp/session_12345';
await agentLoop('Get page title', sessionUrl);

The key insight is that the session persists. If the agent needs to log in, navigate multiple pages, or handle a multi-step form, it can do so without re-establishing the browser context.

Handling Authentication and Profiles

Many agents need to access authenticated areas. You have two options:

1. Pre-configured profiles: Log in once manually via the Remote Browser dashboard. Save the profile. Every new session with that profile starts logged in.
2. Programmatic login: Have the agent perform the login flow each time. Store cookies in the profile after the first run.

The first option is more reliable for production. It avoids flaky login flows and CAPTCHAs during agent execution.

To set up a pre-configured profile:

1. Create a session with a named profile.
2. Open the live viewer.
3. Manually log in to your target site.
4. The profile saves the session state.
5. Future sessions with the same profile inherit the login.

This approach is especially useful for browser-use custom integrations where you need consistent, authenticated access.

Debugging and Observability

When your agent runs in the cloud, you can't open DevTools locally. Remote Browser provides a live viewer for each session. You can watch the browser in real-time, see what the agent sees, and intervene if necessary.

For programmatic debugging, use CDP events. You can log console messages, network requests, and page errors directly to your application.

const client = await context.newCDPSession(page);

// Log all console messages
client.on('Runtime.consoleAPICalled', (event) => {
  console.log(`Console: ${event.args.map(a => a.value).join(' ')}`);
});

// Log all page errors
client.on('Runtime.exceptionThrown', (event) => {
  console.error(`Page error: ${event.exceptionDetails.text}`);
});

This gives you full visibility into what the browser is doing without manual inspection.

Cost Considerations

A custom runtime is metered. You pay for the time a browser session is active, not for idle time between tasks. This means you should design your agent to:

• Reuse sessions for multiple tasks
• Close sessions when they are no longer needed
• Use persistent profiles to avoid re-authentication overhead

For current pricing details, check the pricing page. The cost model is straightforward: you pay per browser-hour, and you can set limits on your account to prevent runaway usage.

Security and Isolation

When running multiple agents, session isolation is critical. You don't want one agent's actions to affect another's data or state. Remote Browser isolates each session by default. Even if two sessions use the same profile, they operate independently.

For sensitive workloads, you can also configure network-level isolation. This ensures that traffic from one session cannot interfere with another.

When to Use a Custom Runtime

You need a browser-use custom setup if:

• Your agent runs longer than a few minutes
• You need to maintain login state across runs
• You are accessing geo-restricted content
• You need to scale beyond one local machine
• You want to avoid bot detection

If your use case is a simple, short-lived script that runs once, a local browser might suffice. But for anything production-grade, a hosted runtime is the practical choice.

Getting Started

To build your own custom runtime with Remote Browser:

1. Create an account and get an API key.
2. Read the documentation for the full API reference: Documentation.
3. Set up a test session and connect with Playwright or Puppeteer.
4. Configure profiles and proxies based on your target sites.
5. Deploy your agent and monitor it via the live viewer.

For more context on why hosted browsers are the missing runtime layer for AI agents, see our post on remote browsers for AI agents. You can also explore how to run a remote browser online or understand the practical runtime for browser automation.

Conclusion

A browser-use custom setup is not just about connecting an LLM to a browser. It is about building a reliable, scalable execution environment. Remote Browser gives you the infrastructure—hosted Chromium, CDP access, persistent profiles, and proxy controls—so you can focus on your agent's logic.

Start with a simple session, add a persistent profile, and iterate. The flexibility of CDP means you can customize every aspect of the browser behavior to match your requirements. Whether you are scraping data, testing UI, or automating workflows, a hosted runtime is the foundation you need.

For a deeper dive into controlling sessions programmatically, check our guide on the browser session API. And if you are comparing options, our analysis of browser-use alternatives provides a useful benchmark.

---

*External reference: For more on CDP, see the Chrome DevTools Protocol documentation.*