Skip to main content
Every Webcompute surface uses the same managed browser runtime. Start with the surface that matches where the browser work lives, then move deeper only when the workflow needs more control.

​
Default recommendation

SituationStart here
You are evaluating WebcomputeRun web agent from the quickstart.
The browser task belongs in your appUse SDK web.agent().
Your code must own every actionUse SDK web.browser and browser.playwright.execute().
A coding-agent host needs a browserUse MCP runtime tools.
You need one scrape, screenshot, or PDFUse quick actions.
You already have a browser frameworkAttach through CDP, then use Webcompute APIs when you need observations or resources.
Do not start with raw REST or CDP unless your integration boundary requires it. They are useful surfaces, but they are lower-level than the CLI, SDK, MCP runtime tools, and quick actions.
You want toUseWhy
Run a browser task from the terminalweb agentFastest way to prove a delegated browser workflow
Embed delegated browsing in an appSDK web.agent()Model-backed browser work with policy, approvals, structured output, and artifacts
Control every browser actionSDK web.browser and browser.playwright.execute()Deterministic Playwright code against a managed browser
Give a coding agent a browserMCP manage_browsers and execute_playwright_codeThe host writes focused Playwright snippets and reads observations after each step
Let a coding agent delegate the whole taskMCP run_web_agentOptional higher-level goal execution when the MCP surface is agent or all
Integrate from another languageREST and OpenAPILanguage-neutral browser lifecycle, execution, resources, and quick actions
Reuse an existing automation stackCDP URLAttach external browser frameworks when protocol-level interop matters
Capture one page quicklyQuick actionsScrape, screenshot, or PDF a URL without owning browser lifecycle

​
Start with web agent

Use web agent when you want a browser task to work before you design an application around it. 
web agent \
  --url https://www.sec.gov/edgar/search/ \
  --allow-domain sec.gov \
  "Find Apple's latest 10-Q filing. Return the filing date, accession number, filing URL, and a one-sentence summary."
Add --debug-url only when you intentionally want a signed live-browser link in the output.

​
Move delegated work into web.agent()

Use the SDK agent harness when the same task belongs in your app, worker, queue, or backend service. 
import { Web } from "@webcompute/sdk";

const web = new Web();

const agent = web.agent({
  model: {
    route: "openrouter",
    model: "openai/gpt-5.4-mini",
    apiKeyEnv: "OPENROUTER_API_KEY",
  },
  browser: {
    create: { recording: true },
    policy: { allowedDomains: ["sec.gov"] },
  },
  approval: "ask",
});

const result = await agent.run({
  startUrl: "https://www.sec.gov/edgar/search/",
  goal:
    "Find Apple's latest 10-Q filing. Return the filing date, accession number, filing URL, and a one-sentence summary.",
});
Use web.agent() when the model should decide the browser steps. Use direct Playwright execution when your code should decide them.

​
Use Playwright execution for exact control

Use web.browser when you want deterministic browser code, explicit cleanup, and direct access to resources. 
import { Web } from "@webcompute/sdk";

const web = new Web();
const browser = await web.browser.create({
  recording: true,
  policy: { allowedDomains: ["example.com"] },
});

try {
  const result = await browser.playwright.execute({
    code: `
      await page.goto("https://example.com");
      return {
        title: await page.title(),
        heading: await page.getByRole("heading").first().textContent(),
      };
    `,
  });

  console.log(result.result);
} finally {
  await browser.close();
}
Prefer user-facing Playwright locators such as getByRole, getByLabel, and getByText. Webcompute returns the code result and, when capture is enabled, bounded status and observation data you can use for the next step.

​
Use MCP for coding agents

Use MCP when Codex, Claude Code, Cursor, OpenCode, Devin, or another MCP host should operate a browser. 
web mcp setup codex --surface runtime
The runtime surface exposes two primary tools:
ToolUse it for
manage_browsersCreate, list, inspect, stop, resume, close, and retrieve Debug UI or CDP URLs.
execute_playwright_codeRun focused Playwright snippets and receive result, status, logs, artifacts, and observation.
Optional agent mode adds run_web_agent: 
web mcp setup codex --surface all --model browsing
Use run_web_agent only when you want Webcompute’s model-backed harness to own the browsing goal. Use the runtime tools when the host should plan each step.

​
Use REST, CDP, or quick actions

Use REST when TypeScript is not the application boundary. The OpenAPI reference covers browser lifecycle, Playwright execution, resources, recordings, events, dialogs, permissions, and quick actions. Use CDP when an existing framework must attach directly to the browser. Direct CDP clients do not automatically receive Webcompute post-step observations; use Webcompute execution APIs when agent-readable observations matter. Use quick actions when you need one scrape, screenshot, or PDF and do not need a persistent browser session.
Debug UI and CDP URLs are signed bearer capabilities. Treat them like credentials.

​
Move between paths

Most teams start with one surface and then move as the workflow becomes more specific:
StartMove whenNext path
web agentThe task belongs in product codeSDK web.agent()
SDK web.agent()A step must be exact or validatedbrowser.playwright.execute() before or after the agent run
MCP runtime toolsThe workflow becomes a product featureSDK browser lifecycle and Playwright execution
Quick actionsThe job needs state, files, downloads, dialogs, or recordingsManaged browser lifecycle
CDPYou need Webcompute observations or resource APIsSDK or REST execution APIs
Read what Webcompute returns when the output shape is the deciding factor.

​
Next steps

Run the CLI quickstart

Install Webcompute, configure model access, run a public browser task, and inspect the result.

Build with the SDK

Move a proven agent task into application code.

Execute Playwright code

Control browser steps directly with normal Playwright.

Connect MCP

Give a coding-agent host a managed browser runtime.

For coding agents

Give an agent host the exact runtime contract: lifecycle, Playwright snippets, observations, and cleanup.