# Browser Cloud

> browser-cloud — agent skill for TestMu AI Browser Cloud. Generates production-ready TypeScript code to spin up cloud browser sessions, connect via Puppeteer/Playwright/Selenium, and run agent workflows — with stealth, auth persistence, file transfer, tunnel access, and full observability baked in. Trigger on: "use browser cloud", "browser agent", "scrape with cloud browser", "automate browser for agent", "cloud puppeteer", "cloud playwright", "headless cloud", "spin up browser session", "TestMu browser", "browser cloud session", "web scraping agent", "fill form with agent", "screenshot from cloud", "PDF from cloud", "browser automation agent", "agent browser task", or any request to connect an AI agent to the web via a real browser. Agent-agnostic: works with LangChain, CrewAI, AutoGen, raw LLM tool calls, and custom agent loops.

- Skill: `lambdatest/browser-cloud` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add lambdatest/browser-cloud`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lambdatest/browser-cloud/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: LambdaTest (https://skillmd.com/u/lambdatest)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lambdatest/browser-cloud

---


# browser-cloud

You write production-grade TypeScript code that connects AI agents to the real web using TestMu AI Browser Cloud. No local Chrome required. Agents get real, stealth-patched, observable cloud browsers on demand.

---

## What You Build

Every output from this skill is runnable TypeScript that:
- Creates an isolated cloud browser session on TestMu AI infrastructure
- Connects via the agent's preferred adapter (Puppeteer / Playwright / Selenium)
- Executes the requested browser task (scrape, screenshot, PDF, form fill, auth, etc.)
- Handles cleanup and observability automatically
- Integrates into the agent's framework without friction

---

## Step 1 — Understand the Request

Extract these before writing code:

| Signal | What to determine |
|--------|-------------------|
| **Task type** | Scrape content, screenshot, PDF, form fill, login + persist, monitor, download file, interact with app |
| **Agent framework** | LangChain, CrewAI, AutoGen, OpenAI functions, custom loop, or standalone script |
| **Adapter preference** | Puppeteer (default), Playwright, or Selenium |
| **Auth needed** | Does the target site require login? Reuse session? |
| **Local access** | Does the agent need localhost or internal URLs? → tunnel |
| **Stealth needed** | Is the target behind bot detection? |
| **Scale** | Single run vs. repeated cron vs. parallel agents |

**If the user does not specify adapter:** default to Puppeteer.
**If the user does not specify framework:** output a standalone async function the user can wrap into any framework.

---

## Step 2 — Choose the Right Pattern

Read the task and match it to one of these patterns. Each has a reference implementation in `/references/`.

| Pattern | When to use | Reference |
|---------|-------------|-----------|
| **Quick Action** | One-off scrape, screenshot, or PDF — no interaction needed | `references/patterns/quick-actions.md` |
| **Session + Navigate** | Multi-step navigation, form interaction, JS-heavy pages | `references/patterns/session-navigate.md` |
| **Auth + Profile** | Login once, reuse session across runs (cron / serverless) | `references/patterns/auth-profile.md` |
| **Parallel Sessions** | Multiple agents / tasks running simultaneously | `references/patterns/parallel-sessions.md` |
| **Tunnel + Localhost** | Agent must reach local dev server, staging, or VPN URLs | `references/patterns/tunnel.md` |
| **LangChain Tool** | Wrap browser actions as LangChain Tool for agent chain | `examples/langchain-browser-tool.ts` |
| **CrewAI Tool** | Wrap as CrewAI BaseTool for crew workflows | `references/integrations/crewai.md` |
| **OpenAI Function** | Define as function_call / tool for GPT-4 agent loops | `references/integrations/openai-functions.md` |
| **File Upload/Download** | Agent needs to upload docs or download reports from cloud browser | `references/patterns/files.md` |

---

## Step 3 — Write the Code

### Non-negotiable rules for every code output

1. **Always use `try/finally` to release sessions.** Sessions left open waste quota and money.
2. **Credentials via env vars only.** Never hardcode `LT_USERNAME` or `LT_ACCESS_KEY`.
3. **Name builds and tests.** Always set `build` and `name` in `lambdatestOptions` — makes runs easy to find in the [TestMu AI](https://testmuai.com/) automation dashboard.
4. **Set explicit timeout.** Default is 5 min. Agent workflows often need 10–30 min: `timeout: 1800000`.
5. **Return structured data.** Agent tools must return typed objects, not raw strings. Define an interface.
6. **Export the function.** All agent tools should be exportable, not just top-level scripts.
7. **Install the SDK if the project does not have it.** Before writing or running Browser Cloud code in the user's repo, check `package.json`: if `@testmuai/browser-cloud` is missing from `dependencies` or `devDependencies`, install it using the project's package manager (detect via lockfile: `pnpm-lock.yaml` → `pnpm add @testmuai/browser-cloud`, `yarn.lock` → `yarn add @testmuai/browser-cloud`, else `npm i @testmuai/browser-cloud`). If there is no `package.json` in the workspace, run `npm init -y` then `npm i @testmuai/browser-cloud` in the intended project root, or add the dependency in the manifest the user is using. Do not skip install when you have shell access and the dependency is absent.

### Code template — base structure

```typescript
import { Browser } from '@testmuai/browser-cloud';

const client = new Browser();

export interface BrowserTaskResult {
  success: boolean;
  data?: unknown;
  error?: string;
  sessionViewerUrl?: string;
}

export async function browserTask(input: string): Promise<BrowserTaskResult> {
  const session = await client.sessions.create({
    adapter: 'puppeteer',
    timeout: 1800000,
    stealthConfig: {
      humanizeInteractions: true,
      randomizeUserAgent: true,
    },
    lambdatestOptions: {
      build: 'Agent: <TaskName>',
      name: input.slice(0, 80),
      'LT:Options': {
        username: process.env.LT_USERNAME!,
        accessKey: process.env.LT_ACCESS_KEY!,
        video: true,
        console: true,
      },
    },
  });

  try {
    const browser = await client.puppeteer.connect(session);
    const page = (await browser.pages())[0];

    // --- task logic here ---

    await browser.close();
    return { success: true, data: null, sessionViewerUrl: session.sessionViewerUrl };
  } catch (err) {
    return { success: false, error: String(err) };
  } finally {
    await client.sessions.release(session.id);
  }
}
```

---

## Step 4 — Add the Right Capabilities

Layer in only what the task actually needs. Do not add capabilities the task does not require.

### Stealth (bot detection avoidance)
Add when: target site has Cloudflare, bot.sannysoft.com-style checks, or blocks headless browsers.
```typescript
stealthConfig: {
  humanizeInteractions: true,  // random delays on click/type
  randomizeUserAgent: true,    // pool of 7 real Chrome/Firefox UAs
  randomizeViewport: true,     // ±20px jitter on viewport
}
```

### Auth persistence across runs
Add when: agent logs in to a service and runs on a schedule or as serverless.
```typescript
// In session config:
profileId: 'service-name-login',  // auto-saves cookies on browser.close()

// On first run, agent logs in normally.
// On all subsequent runs, cookies are restored — login page is skipped.
```
See full pattern: `references/patterns/auth-profile.md`

### Tunnel (localhost / staging access)
Add when: agent must reach `localhost`, `*.internal`, or VPN-gated URLs.
```typescript
tunnel: true,
tunnelName: 'agent-tunnel',
// Then: await page.goto('http://localhost:3000') works from the cloud.
```

### Context transfer (session-to-session auth in same script)
Add when: agent creates multiple sessions in one script run and needs to share login state.
```typescript
// After login in session 1:
const ctx = await client.context.getContext(page1);

// In session 2:
await client.context.setContext(page2, ctx);
// Already authenticated — no re-login.
```

### Parallel sessions
Add when: agent runs multiple browser tasks concurrently.
```typescript
const results = await Promise.all(
  urls.map(url => browserTask(url))
);
```
Always add `releaseAll()` in the shutdown handler:
```typescript
process.on('SIGINT', async () => { await client.sessions.releaseAll(); process.exit(0); });
```

---

## Step 5 — Framework Integration

### LangChain (TypeScript)
```typescript
import { Tool } from 'langchain/tools';

class BrowserCloudTool extends Tool {
  name = 'browser-cloud';
  description = 'Browse any URL, scrape content, take screenshots, or fill forms using a real cloud browser. Input: URL or task description.';

  async _call(input: string): Promise<string> {
    const result = await browserTask(input);
    return JSON.stringify(result);
  }
}
```

### CrewAI (Python — call SDK via subprocess or API when REST is available)
See `references/integrations/crewai.md` for the wrapper pattern using the planned REST API or a Node.js subprocess bridge.

### OpenAI function calling
See `references/integrations/openai-functions.md` for the function definition schema and handler.

### Standalone / custom agent loop
The exported function works directly — call it from any async context, pass the result back to the LLM.

---

## Adapter Selection Guide

| Scenario | Use |
|----------|-----|
| Most agent use cases | **Puppeteer** — best stealth, simplest return type (`Browser`) |
| Complex form interaction, auto-waiting | **Playwright** — `page.fill()`, built-in waits, returns `{browser, context, page}` |
| Existing Selenium test suite | **Selenium** — connects to TestMu hub via HTTP/WebDriver |
| Node.js < 18 | **Puppeteer or Selenium** — Playwright requires Node 18+ |

---

## Quick Actions (no session management)

For one-off operations where the agent does not interact beyond data extraction:

```typescript
// Scrape — format options: 'html' | 'text' | 'markdown' | 'readability'
const scraped = await client.scrape({ url, format: 'markdown', waitFor: '#content' });

// Screenshot
const shot = await client.screenshot({ url, fullPage: true, format: 'png' });
fs.writeFileSync('out.png', shot.data);

// PDF
const pdf = await client.pdf({ url, format: 'A4', printBackground: true });
fs.writeFileSync('out.pdf', pdf.data);
```

Quick Actions spin up a temporary headless browser, execute, and clean up automatically.

---

## Output Checklist

Before finalizing any code output, verify:

- [ ] `@testmuai/browser-cloud` is listed in `package.json` or was installed in this session when it was missing
- [ ] Credentials come from `process.env.LT_USERNAME` and `process.env.LT_ACCESS_KEY`
- [ ] `try/finally` wraps all browser work with `client.sessions.release(session.id)` in finally
- [ ] `build` and `name` set in `lambdatestOptions`
- [ ] `timeout` set explicitly (not relying on 5-min default for agent workflows)
- [ ] Function is exported and accepts typed input, returns typed output
- [ ] Stealth config included if the target site is likely to block headless browsers
- [ ] `SIGINT` handler added if the script manages multiple sessions or runs as a long-lived process
- [ ] `.env` file setup instructions included in comments or a README block

---

## Reference Files in This Skill

```
references/
  patterns/
    quick-actions.md        — scrape / screenshot / PDF one-liners
    session-navigate.md     — multi-step navigation and interaction
    auth-profile.md         — login once, persist across runs
    parallel-sessions.md    — concurrent agent sessions
    tunnel.md               — localhost and internal network access
    files.md                — upload/download between agent and cloud browser
  integrations/
    crewai.md               — CrewAI BaseTool wrapper (Python + subprocess bridge)
    openai-functions.md     — OpenAI and Anthropic function calling definition
examples/
  scrape-agent.ts           — standalone scraping agent
  form-fill-agent.ts        — form interaction with stealth
  auth-persist-agent.ts     — login + profile persistence
  parallel-research.ts      — parallel scraping across multiple URLs
  langchain-browser-tool.ts — LangChain tools: scrape, screenshot, multi-action, structured
```

---

## Environment Setup (always include in output)

If the user's project already declares `@testmuai/browser-cloud`, skip reinstall unless they ask to upgrade. Otherwise install per **non-negotiable rule 7** above, then document the command you used.

```bash
npm i @testmuai/browser-cloud
# Node.js 16+ required. Playwright adapter requires Node 18+.
```

```
# .env
LT_USERNAME=your_testmuai_username
LT_ACCESS_KEY=your_testmuai_access_key
```

Credentials: [TestMu AI](https://testmuai.com/) → sign in → **Account Settings** (same username/access key pair as for Browser Cloud / automation).

Session logs: After each run, video, console, and network capture appear in your TestMu AI automation session history (open the dashboard from [testmuai.com](https://testmuai.com/) after sign-in).