Skip to content

Web search and browsing

Search the web, read a page and open a browser from a workspace, through the bindings of the Worker.

Updated

A workspace searches the web and opens a browser through the Worker’s bindings. You create no key and no token.

Run cf-opencode-search inside the workspace:

cf-opencode-search "cloudflare containers snapshots"

It prints a numbered list. Each result has a title, a URL and a short description.

Flag Effect
-n <1..10> The number of results. The default is 5.
--provider <name> The search provider for this search: exa, linkup or ceramic.
--json Print the answer of the Web Search API as JSON.

The Worker runs the search with the Cloudflare Web Search API, through its AI binding and your AI Gateway. Searches bill to your AI Gateway credits at the price of the provider. The default provider is exa. To change it, set searchProvider in ~/.cf-opencode/config.json and run cf-opencode upgrade.

The notes that the agent reads tell it to use this command. OpenCode also has its own web search tool. That tool uses the provider of OpenCode, not your Cloudflare account.

With lockdown on, cf-opencode-fetch is refused. See Security and trust.

A search with no credits on the account fails with a Failed: line. Add AI Gateway credits in the Cloudflare dashboard.

Read a page

Run cf-opencode-fetch inside the workspace:

cf-opencode-fetch https://developers.cloudflare.com/containers/

It prints the page as Markdown. The Worker loads the page in a real browser with Browser Run Quick Actions, so a page that needs JavaScript works.

Flag Effect
--links Print the links on the page, one for each line.
--html Print the rendered HTML.
--screenshot <file> Save a screenshot as a PNG file.
--pdf <file> Save the page as a PDF file.
--max-chars <n> Cut the text after n characters. The default is 60000. 0 prints all.

Each call uses a new browser and closes it. It bills to the Browser Run usage of your account. Use a browser session when you must click, type or stay logged in.

Browser

A workspace browses through Browser Run. The Worker has a Browser Run binding. You create no token. Browser sessions bill to the account that owns the Worker.

The container never reaches Browser Run itself. It asks the Worker for a session. The Worker relays the browser protocol (CDP) frames.

From your machine

cf-opencode browse my-repo

The command opens a session and prints a websocket URL on your Worker. If the session has a live view, it prints live: <url> on stderr.

Connect a CDP client to the websocket URL. Use Basic authentication with the user opencode and the workspace password. The URL works only with the password of the workspace that opened the session. A client that sends an Origin header must send the Worker’s own origin (https://…). Some libraries add another one by themselves, and get HTTP 403: send no Origin header then (Python websocket: suppress_origin=True). A web page is refused, on another site or on the Worker’s own origin.

browse needs the local password file. Run cf-opencode connect my-repo first.

From inside the workspace

The command cf-opencode-browse does the same. It reads the password from OPENCODE_SERVER_PASSWORD. OpenCode’s tools have that variable, so the agent can open a browser from its shell tool.

cf-opencode-browse

cf-opencode-browse --preview <port> also lets the session open the dev server of the workspace on that port as http://p<port>.preview.internal/. You can repeat the flag for up to 4 ports. See Preview a dev server.

The command prints the websocket URL, and a Python line that connects to it. Use the header Authorization: Basic base64(opencode:$OPENCODE_SERVER_PASSWORD).

Billing and time limit

A browser session bills per browser hour on your Cloudflare account. A session closes after 10 minutes without activity. See the Browser Run pricing for current rates.

Errors

Error Fix
this Worker has no Browser Run binding Run cf-opencode init again to redeploy.
no local password for <workspace> Run cf-opencode connect <workspace>.
browser session … is gone Open a new session with cf-opencode browse.

Type to search…

↑↓ navigate↵ selectEsc close