infochanged

Agents, Browser Run - Agents SDK: Preview dev servers in the browser without public URLs

Announced: 2026-10-28
Tags: Agents, Browser-Run
Severity: info, set by reef/rss-rule-v1
Source: https://developers.cloudflare.com/changelog/post/2026-10-28-browser-internal-hostnames/

Agents that build websites need to check their work in a real browser. Internal hostnames let your agent's browser preview a dev server running in a container without exposing that server to the public Internet. With internal hostnames, the <a href="https://developers.cloudflare.com/agents/tools/browser/">persistent browser</a> in the <a href="https://developers.cloudflare.com/agents/">Cloudflare Agents SDK</a> can open sites that only your agent serves. Give the browser hostnames such as <code>preview.internal</code>, and its requests to them go to your agent instead of the Internet. The model can check a dev server in its sandbox, a folder in its workspace, or another Worker in the same browser it uses for the web, and nothing is exposed publicly. <img src="https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=960,height=524,format=svg/_astro/browser-internal-hostnames.FAVHfafR.svg" alt="An animated diagram of three kinds of hostname: example.com goes out to the Internet; the model points preview.internal at port 5173 with browser.assignHost(), then the browser opens it and your agent serves it from the sandbox; and api.internal goes straight to another Worker, skipping your agent" loading="lazy" decoding="async" width="960" height="524"> Each internal host has a <code>fetch</code> function that runs in your Durable Object, so it can use the object's bindings and state. A host can also send its requests straight to another Worker through a service binding. Add a <code>target</code> schema to a host, and the model chooses what it serves, such as which port or which folder. Internal hostnames are a capability of the browser, independent of your agent harness. Use the built-in adapters for Pi Durable, AI SDK, and TanStack AI, or connect another harness by implementing a tool with <a href="https://developers.cloudflare.com/agents/tools/browser/#use-another-harness"><code>browser.session()</code></a>. No prebuilt adapter is required. This example adds a private dev-server preview to a <a href="https://developers.cloudflare.com/agents/tools/browser/#use-it-with-pi-durable">Pi Durable agent</a>. Start with that guide's packages, bindings, and request handler, and install <a href="https://github.com/cloudflare/agents/releases/tag/agents%400.31.0" target="_blank" rel="noopener">Agents SDK v0.31.0 ↗︎</a> or later. The example has three parts: <ul> <li>Browser configuration: <code>internalHosts</code> defines how the browser reaches the dev server.</li> <li>Durable Object wiring: Lifecycle and <code>fetchInternalHost()</code> connect the browser to your application.</li> <li>Harness integration: <code>browserTool</code> from <code>agents/browser/pi</code> registers the tool with Pi.</li> </ul> <div><div data-nb-tabs data-nb-sync-key="workersExamples" class><div class="relative flex border-b border-border" role="tablist" data-nb-tabs-list></div><div class="mt-3"><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="JavaScript" class><figure class="nb-code-figure" data-nb-lang="js"><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="js" data-nb-lang="js"><code>import { DurableObject } from "cloudflare:workers"; import { createModels } from "@earendil-works/pi-ai/models"; import { createRegistry, Harness } from "@earendil-works/pi-durable"; import { Browser, browserRun } from "agents/browser"; import { browserTool } from "agents/browser/pi"; import { PiHarness } from "agents/harness/pi"; import { Lifecycle } from "agents/lifecycle"; import { createAI } from "agents/models/pi-ai"; import { z } from "zod"; // Your own code: reach a port on your sandbox and return its Response. import { fetchSandboxPort } from "./hosts"; // Browser Run calls back into your Worker through this entrypoint. export { InternalHostRouter } from "agents/browser"; export class BrowserAssistant extends DurableObject { ai = createAI({ binding: this.env.AI }); registry = createRegistry(); browser = new Browser({ provider: browserRun(this.env.BROWSER, { internalHosts: { router: this.ctx.exports.InternalHostRouter, hosts: { "preview.internal": { description: "Your dev servers", // What the model passes to browser.assignHost() to choose // what this host serves. fetch receives it as its second argument. target: z.object({ port: z.number().int().min(1024) }), fetch: (request, { port }) => fetchSandboxPort(port, request), }, }, }, }), }); harness = new PiHarness({ harness: ({ storage, context, onWake }) => { const models = createModels(); models.setProvider(this.ai.provider); this.registry.install({ name: "browser", tools: [ browserTool({ browser: this.browser, loader: this.env.LOADER }), ], }); return Harness.open( storage, { models, registry: this.registry, onWake }, context, ); }, defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") }, }); lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness); // InternalHostRouter calls this method to reach your Browser. fetchInternalHost(message) { return this.browser.fetchInternalHost(message); } async ask(prompt) { const { text } = await this.harness.prompt(prompt); return text; } }</code></pre></figure></div><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="TypeScript" class><figure class="nb-code-figure" data-nb-lang="ts"><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="ts" data-nb-lang="ts"><code>import { DurableObject } from "cloudflare:workers"; import { createModels } from "@earendil-works/pi-ai/models"; import { createRegistry, Harness } from "@earendil-works/pi-durable"; import { Browser, browserRun, type InternalHostMessage } from "agents/browser"; import { browserTool } from "agents/browser/pi"; import { PiHarness } from "agents/harness/pi"; import { Lifecycle } from "agents/lifecycle"; import { createAI } from "agents/models/pi-ai"; import { z } from "zod"; // Your own code: reach a port on your sandbox and return its Response. import { fetchSandboxPort } from "./hosts"; // Browser Run calls back into your Worker through this entrypoint. export { InternalHostRouter } from "agents/browser"; export class BrowserAssistant extends DurableObject<Env> { ai = createAI({ binding: this.env.AI }); registry = createRegistry(); browser = new Browser({ provider: browserRun(this.env.BROWSER, { internalHosts: { router: this.ctx.exports.InternalHostRouter, hosts: { "preview.internal": { description: "Your dev servers", // What the model passes to browser.assignHost() to choose // what this host serves. fetch receives it as its second argument. target: z.object({ port: z.number().int().min(1024) }), fetch: (request, { port }) => fetchSandboxPort(port, request), }, }, }, }), }); harness = new PiHarness({ harness: ({ storage, context, onWake }) => { const models = createModels(); models.setProvider(this.ai.provider); this.registry.install({ name: "browser", tools: [ browserTool({ browser: this.browser, loader: this.env.LOADER }), ], }); return Harness.open( storage, { models, registry: this.registry, onWake }, context, ); }, defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") }, }); lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness); // InternalHostRouter calls this method to reach your Browser. fetchInternalHost(message: InternalHostMessage) { return this.browser.fetchInternalHost(message); } async ask(prompt: string) { const { text } = await this.harness.prompt(prompt); return text; } }</code></pre></figure></div></div></div><script type="module" src="https://developers.cloudflare.com/home/runner/work/cloudflare-docs/cloudflare-docs/src/components/ui/tabs/Tabs.astro?astro&type=script&index=0&lang.ts"></script></div> To use another harness, keep the browser configuration. Choose a <a href="https://developers.cloudflare.com/agents/tools/browser/#use-another-harness">browser-tool adapter</a> if one is available, or implement a tool using <code>browser.session()</code>. <code>browserTool</code> tells the model about each host, including the schema of its <code>target</code>. Because <code>preview.internal</code> has a <code>target</code> schema, the model can choose which port it serves. To check its dev server, the model calls <code>browser.assignHost()</code> with a target that matches the schema, such as <code>{ port: 5173 }</code>, and opens the URL it gets back: <figure class="nb-code-figure" data-nb-lang="js"><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="js" data-nb-lang="js"><code>const { url } = await browser.assignHost({ host: "preview.internal", target: { port: 5173 }, }); await browser.cdp({ method: "Page.navigate", params: { url }, sessionId: "active", });</code></pre></figure> The target is checked against the schema and stored, so it lasts across turns, browser restarts, and redeploys. Each request to <code>http://preview.internal/</code> then calls the host's <code>fetch</code> function with <code>{ port: 5173 }</code>. This release also simplifies <code>browserTool</code>. It runs the model's code in its own <a href="https://developers.cloudflare.com/dynamic-workers/">Dynamic Worker</a> and no longer needs a <code>CodemodeRuntime</code> export. Refer to the <a href="https://github.com/cloudflare/agents/releases/tag/agents%400.31.0" target="_blank" rel="noopener">v0.31.0 upgrade notes ↗︎</a> if you already use <code>browserTool</code>. For the complete example, limits, and security guidance, refer to <a href="https://developers.cloudflare.com/agents/tools/browser/#internal-hostnames">Internal hostnames</a>.

The text above is the source's. reef added the severity, the dates it could read from the text, and the endpoints and scopes named in code.