---
title: "Web search and browsing"
description: "Search the web, read a page and open a browser from a workspace, through the bindings of the Worker."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Web search and browsing

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

## Web search

Run `cf-opencode-search` inside the workspace:

```sh
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](https://cf-opencode.system3inference.dev/docs/concepts/security/#lockdown).

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:

```sh
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

```sh
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.

```sh
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](https://cf-opencode.system3inference.dev/docs/guides/preview/#the-agents-own-browser).

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](https://developers.cloudflare.com/browser-run/) 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`. |

Source: https://cf-opencode.system3inference.dev/docs/guides/browsing/index.mdx
