The latest Agents SDK release adds support for internal hostnames that the built‑in browser can resolve directly to an agent’s Durable Object. By assigning names such as preview.internal, the browser routes requests to the agent instead of the public Internet, allowing developers to preview sandboxed services, folder assets, or other Workers without opening a public endpoint.
How Internal Hostnames Work
Each internal hostname is backed by a fetch implementation inside a Durable Object. The object can use its bindings and state, so the preview can access databases, KV stores, or other resources the agent already owns. A hostname may also include a target schema that tells the browser which port, folder, or downstream Worker to invoke. When the browser issues a request to preview.internal, the SDK intercepts the DNS lookup, maps it to the Durable Object, and runs the associated fetch handler. This mechanism is part of the browser capability itself and does not depend on any particular harness.
Integrating with a Pi Durable Agent
In a Pi Durable workflow the integration consists of three steps:
- Browser configuration: define an
internalHostsmap that links hostnames to fetch logic. - Durable Object wiring: implement a
fetchInternalHost()method that forwards the request to the appropriate sandbox port or folder. - Harness registration: use
browserToolfromagents/browser/pito expose the browser as a tool within the Pi harness.
A minimal configuration looks like this:
const internalHosts = {
"preview.internal": { port: 5173 },
"api.internal": { target: "worker", binding: "API_WORKER" }
};
With Agents SDK v0.31.0 or later, the Pi Durable example can import Browser, browserRun, and the Pi‑specific tool, then register the tool during harness initialization. No additional adapters are required; the browser session API can be used to plug in custom harnesses if needed.
Operational and Security Implications
Because the preview traffic never leaves the agent’s environment, the public attack surface is unchanged. The internal hostname resolves only inside the browser sandbox, so external users cannot reach the dev server. This also means that any bindings the Durable Object holds—such as secret‑backed KV or R2—are available to the preview without exposing them to the Internet.
Practitioners should consider the following:
- Namespace collisions: ensure internal hostnames are unique within the agent to avoid accidental routing.
- Resource limits: the preview runs inside the same Durable Object instance, so CPU and memory quotas apply.
- Observability: logs from the
fetchInternalHosthandler appear alongside normal Durable Object logs, enabling unified monitoring. - Adapter flexibility: while built‑in adapters exist for Pi Durable, AI SDK, and TanStack AI, teams can implement a custom tool via
browser.session()without waiting for a pre‑built package.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Adopt internal hostnames when you need to test services that rely on private bindings or when exposing a temporary public URL is undesirable. Update your Agents SDK to v0.31.0+, add an internalHosts map, and wire the corresponding fetchInternalHost logic. Monitor the Durable Object for any unexpected load, and keep hostname definitions documented to avoid conflicts. This pattern provides a low‑risk, high‑fidelity preview workflow that aligns with secure development practices.
