Skip to Content
Tile TypesRemote Preview

Remote Preview

A remote preview tile renders an external HTTPS origin inside your workspace — a deployed Cloudflare Worker, a Pages site, a staging service, or any publicly reachable URL. It looks and behaves like a regular preview tile, except the page it shows is hosted somewhere outside the workspace instead of by a dev server running inside it.

This replaces the pattern of standing up a hand-rolled proxy inside the workspace just to view a deployed service. The proxying, header handling, and access control are all handled for you.

The allowlist is the security boundary

A remote preview only works if the target origin has been added to the workspace’s remote-origin allowlist by an operator. This is the load-bearing security control:

  • Only an operator can edit the allowlist. Agents have no way to add an origin themselves — they can request a remote preview, but it renders only if the origin is already allowlisted.
  • Adding an origin is a deliberate act of sanctioning a specific external destination for this workspace. Nothing reaches a remote origin until you’ve explicitly added it.

This keeps agents from previewing arbitrary external URLs and turns “preview a remote service” into “expose a remote view you chose to allow.”

Allowing a remote origin

Open the workspace settings, find Remote Previews, and manage the list of allowed origins. From there you can add, label, and remove HTTPS origins.

Each entry has a match mode that controls which URLs may be previewed:

  • Full origin — any path under the origin is previewable. Example: allowing https://example.com permits https://example.com/anything.
  • Origin + path prefix — only paths that begin with a prefix you set are previewable. The match is boundary-aware: a prefix of /api/v1 matches /api/v1/users but not /api/v10/users. Use this to expose one route of a multi-route service without exposing the rest.

What can’t be allowlisted

The add form only accepts public HTTPS origins. It rejects:

  • Non-HTTPS URLs.
  • Loopback and localhost addresses.
  • Private network ranges (RFC 1918), link-local (169.254.x.x), and CGNAT (100.64.x.x) addresses.

For servers running inside your workspace, use a normal port-based preview tile instead — those don’t go through the allowlist.

How an agent requests a remote preview

An agent creates a remote preview through the same MCP tool as a local one, passing a URL instead of a port (a name is required either way):

studio.create_preview(name="my-worker", url="https://my-worker.workers.dev/")
  • If the origin is allowlisted, the tile appears in the workspace and renders the remote page. A clear badge marks it as a remote preview so you can tell at a glance what’s being proxied.
  • If the origin is not allowlisted, the request comes back with a friendly, structured reason: the origin hasn’t been allowed yet. The recovery path is simply for you to add it in workspace settings, after which the agent can try again.

For an origin + path prefix entry, the requested URL must start with the configured prefix — a URL outside the prefix is treated the same as one that isn’t allowlisted at all.

What you get and what’s enforced

  • Access is workspace-scoped. Only members of the workspace can reach a remote preview; every request is authenticated.
  • The origin is re-checked on every request, not just when the tile is created — so removing an origin from the allowlist immediately stops any live tiles pointing at it.
  • Page-framing headers are handled for you so the remote page renders inside the workspace. The proxy never follows redirects itself, so nothing it fetches comes from outside the allowlisted origin; a redirect is handed to the browser as-is, and a page it lands on elsewhere isn’t proxied.
  • Your workspace credentials are never sent to the remote origin. Remote previews target public origins; if a remote service needs authentication, handle that on the service side.
Last updated on
PreviewAgent Browser