Browser & web tools

Revka gives your agent several ways to reach the web, ranging from a single click-to-open action to full DOM automation and arbitrary HTTP calls. This page is the reference for all of them: browser, browser_open, browser_delegate, text_browser, web_fetch, web_search_tool, and http_request, plus the [browser], [web_fetch], [web_search], and [http_request] config sections that gate them.

Pick the lightest tool that does the job. For reading a static page, web_fetch or text_browser are faster and cheaper than spinning up a real browser. Reach for browser only when a page needs JavaScript rendering, login, or interaction. For step-by-step setup of the browser backends, VNC debugging, and agent-browser installation, see Browser automation — this page focuses on the tool surface and config keys.

Note

Every web tool enforces a deny-by-default domain allowlist and blocks local and private hosts unless you explicitly opt in. The browser and browser_open tools are also in the default OTP gating list — see OTP gating & emergency stop.

Choosing a tool

Tool	Use it for	Interaction	Config gate
browser_open	Opening an approved HTTPS URL in the system browser	None (open only)	[browser]
browser	Full DOM and OS-level automation	Click, fill, type, screenshot, scroll, etc.	[browser]
browser_delegate	Corporate web apps via an external CLI	Natural-language task	[browser_delegate]
text_browser	Rendering a page as plain text in headless/SSH environments	None (read only)	[text_browser]
web_fetch	Fetching a page as clean plain text (GET only)	None (read only)	[web_fetch]
web_search_tool	Searching the web for titles, URLs, and descriptions	None	[web_search]
http_request	Arbitrary HTTP calls to external APIs	All HTTP methods	[http_request]

browser_open

Opens an approved HTTPS URL in the system browser. There is no scraping and no interaction — it simply launches the page. Navigation is restricted to the [browser].allowed_domains allowlist, HTTPS only, and local/private hosts are rejected.

{"url": "https://docs.example.com"}

Parameter	Type	Required	Meaning
url	string	yes	HTTPS URL to open

browser_open shares the [browser] config section and allowed_domains allowlist with the full browser tool. Both are enabled by [browser].enabled.

browser

Full web automation with three pluggable backends. The browser tool exposes DOM actions plus optional OS-level actions (the latter only on the computer_use backend).

{"action": "open", "url": "https://example.com"}
{"action": "snapshot"}
{"action": "click", "selector": "@e3"}

Actions

• DOM actions: open, snapshot, click, fill, type, get_text, get_title, get_url, screenshot, wait, press, hover, scroll, is_visible, close, find
• OS-level actions (computer_use backend only): mouse_move, mouse_click, mouse_drag, key_type, key_press, screen_capture

Parameters

Parameter	Type	Meaning
action	string	One of the actions above (required)
url	string	URL to navigate to (for open)
selector	string	Element selector: @ref, CSS, or text=...
value	string	Value to fill
text	string	Text to type or wait for
key	string	Key to press (Enter, Tab, Escape, etc.)
x, y	integer	Screen coordinates for computer_use mouse actions
from_x, from_y, to_x, to_y	integer	Drag source/target coordinates
button	string	left, right, or middle
backend	string	Per-call backend override: agent_browser, native, or computer_use

The @ref selector model

After open, call snapshot to map interactive elements to stable refs (@e1, @e2, @e3). Pass those refs to click, fill, hover, and similar actions. Selectors also accept CSS (button.submit) and text matchers (text=Accept). Re-run snapshot after the page changes — refs are recomputed each time.

Backends

Set the default backend in [browser].backend, or override it per call with the backend parameter:

• agent_browser (default) — drives Chrome for Testing through the agent-browser CLI; the easiest path on a server or container.
• rust_native — a built-in WebDriver backend. Requires the browser-native Cargo feature compiled into your build.
• computer_use — delegates to a computer-use sidecar over HTTP for true OS-level mouse, keyboard, and screenshot actions.
• auto — lets Revka select an available backend automatically.

See Browser automation for backend installation and debugging.

browser_delegate

Hands a natural-language browser task to an external browser-capable CLI subprocess (for example, Claude Code with the claude-in-chrome MCP). It is built for corporate web apps — Teams, Outlook, Jira, Confluence — that have no direct API and are awkward for the headless backends. A persistent Chrome profile can be configured so SSO sessions survive across invocations.

{"task": "Check my unread Teams messages"}

Parameter	Type	Required	Meaning
task	string	yes	Natural-language task description

Caution

browser_delegate spawns a CLI subprocess and therefore requires shell access. It is unavailable in restricted runtimes that disable the shell. Reach for it only when the agent_browser backend isn’t suitable.

text_browser

Renders a web page as plain text using an installed text-based browser (lynx, links, or w3m). It is ideal for headless and SSH environments without a graphical browser, and best for simple HTML pages. JavaScript-heavy sites usually need web_fetch with the Firecrawl fallback instead.

{"url": "https://example.com"}

Parameter	Type	Required	Meaning
url	string	yes	URL to fetch and render as text

If [text_browser].preferred_browser is unset, Revka auto-detects whichever of lynx, links, or w3m is installed.

web_fetch

Fetches a web page and returns clean plain text. HTML is converted to readable text; JSON and plain text are returned as-is. It is GET only and follows redirects. When the standard fetch fails — an HTTP error, an empty body, or a body shorter than 100 characters (suggesting a JavaScript-only page) — it can fall back to the Firecrawl API for stealth content extraction, if Firecrawl is enabled.

{"url": "https://docs.anthropic.com/en/api/getting-started"}

Parameter	Type	Required	Meaning
url	string	yes	HTTPS URL to fetch

web_fetch is opinionated — GET only, output normalized to text. When you need other HTTP methods, custom headers, or a request body, use http_request instead.

web_search_tool

Searches the web and returns titles, URLs, and descriptions of relevant results. It supports multiple provider backends with fallback routing. By default it uses DuckDuckGo, which requires no API key; you can switch to Brave (API key required) or a self-hosted SearXNG instance.

{"query": "Rust async runtime comparison 2026"}

Parameter	Type	Required	Meaning
query	string	yes	Search query

http_request

Makes arbitrary HTTP requests to external APIs. It supports GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS. Navigation is restricted to the [http_request].allowed_domains allowlist, and local/private hosts are rejected unless explicitly allowed.

{
  "url": "https://api.example.com/v1/data",
  "method": "POST",
  "headers": {"Authorization": "Bearer REPLACE_WITH_TOKEN"},
  "body": "{\"key\": \"value\"}"
}

Parameter	Type	Required	Default	Meaning
url	string	yes	—	Target URL
method	string	no	GET	HTTP method
headers	object	no	{}	Key-value HTTP headers
body	string	no	—	Request body for POST/PUT/PATCH

Configuration

All of these tools are configured in ~/.revka/config.toml. See Config: channels, tools & integrations for the complete key reference.

Domain allowlists

Every web tool enforces a domain allowlist with the same semantics:

• ["*"] allows all public domains, but local and private hosts (RFC 1918, loopback, link-local, .local) are still blocked for SSRF protection.
• An empty list ([]) on web_fetch and http_request denies all requests (deny-by-default).
• Specific entries use exact or subdomain matching.
• For web_fetch and browser_delegate, blocked_domains always takes priority over allowed_domains.

To reach a private or internal host, add it to web_fetch.allowed_private_hosts, or set http_request.allow_private_hosts = true.

[browser]

Gates both browser and browser_open.

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"
native_headless = true

Key	Type	Default	Meaning
enabled	bool	false	Master switch for browser and browser_open
allowed_domains	array	[]	Navigation allowlist; "*" allows all public domains
session_name	string	unset	Named browser session (persists auth state)
backend	string	"agent_browser"	agent_browser, rust_native, computer_use, or auto
native_headless	bool	true	Headless mode for the rust-native backend
native_webdriver_url	string	http://127.0.0.1:9515	WebDriver endpoint for the rust-native backend
native_chrome_path	string	unset	Optional Chrome/Chromium executable path

The [browser.computer_use] sub-section configures the OS-level sidecar:

Key	Type	Default	Meaning
endpoint	string	http://127.0.0.1:8787/v1/actions	Sidecar endpoint for OS-level actions
api_key	string	unset	Optional bearer token (stored encrypted)
timeout_ms	integer	15000	Per-action request timeout
allow_remote_endpoint	bool	false	Allow a non-loopback endpoint
window_allowlist	array	[]	Window title/process allowlist forwarded to sidecar policy
max_coordinate_x / max_coordinate_y	integer	unset	Optional coordinate boundaries

Caution

The rust_native backend requires the browser-native Cargo feature in your build — see Cargo feature flags & ADRs. Keep computer_use.allow_remote_endpoint = false (the default) unless you fully control the network path; it rejects non-loopback endpoints to prevent accidental public exposure of the sidecar.

[browser_delegate]

[browser_delegate]
enabled = true
cli_binary = "claude"
chrome_profile_dir = "~/.config/chrome-corp-profile"
allowed_domains = ["teams.microsoft.com", "outlook.office.com"]
blocked_domains = []
task_timeout_secs = 120

Key	Type	Default	Meaning
enabled	bool	false	Enable the browser_delegate tool
cli_binary	string	"claude"	CLI binary to spawn for browser tasks
chrome_profile_dir	string	""	Chrome user-data directory for persistent SSO sessions; empty uses a fresh profile each run
allowed_domains	array	[]	Navigation allowlist; empty permits all non-blocked domains
blocked_domains	array	[]	Denylist; takes precedence over allowed_domains
task_timeout_secs	integer	120	Per-task timeout in seconds

[text_browser]

[text_browser]
enabled = true
preferred_browser = "lynx"   # optional; auto-detects if unset
timeout_secs = 30

Key	Type	Default	Meaning
enabled	bool	false	Enable the text_browser tool
preferred_browser	string	unset	lynx, links, or w3m; auto-detects when unset
timeout_secs	integer	30	Request timeout in seconds

[web_fetch]

[web_fetch]
enabled = true
allowed_domains = ["*"]
blocked_domains = []
allowed_private_hosts = []
max_response_size = 500000
timeout_secs = 30

[web_fetch.firecrawl]
enabled = false
api_key_env = "FIRECRAWL_API_KEY"
api_url = "https://api.firecrawl.dev/v1"
mode = "scrape"

Key	Type	Default	Meaning
enabled	bool	false	Enable the web_fetch tool
allowed_domains	array	["*"]	Allowlist; ["*"] = all public hosts, [] = deny all
blocked_domains	array	[]	Denylist; always takes priority over allowed_domains
allowed_private_hosts	array	[]	Private/internal hosts allowed to bypass SSRF protection
max_response_size	integer	500000	Maximum response size in bytes (500 KB)
timeout_secs	integer	30	Request timeout in seconds

The [web_fetch.firecrawl] sub-section enables the JavaScript/bot-blocked fallback. Set the API key via the env var named by api_key_env (default FIRECRAWL_API_KEY). Only mode = "scrape" is implemented today; crawl is reserved for future use.

[web_search]

[web_search]
enabled = true
provider = "duckduckgo"   # duckduckgo (free), brave, searxng
max_results = 5
timeout_secs = 15
# brave_api_key = "REPLACE_WITH_KEY"          # required for the brave provider
# searxng_instance_url = "https://searx.example.com"   # required for searxng

Key	Type	Default	Meaning
enabled	bool	true	Enable the web_search_tool
provider	string	"duckduckgo"	duckduckgo (free), brave (API key), or searxng (self-hosted)
brave_api_key	string	unset	Brave Search API key (required for brave)
searxng_instance_url	string	unset	SearXNG instance URL (required for searxng)
max_results	integer	5	Maximum results per search (1–10)
timeout_secs	integer	15	Request timeout in seconds

Web search is enabled by default with DuckDuckGo, which needs no API key. These keys also have environment-variable equivalents: WEB_SEARCH_ENABLED, WEB_SEARCH_PROVIDER, WEB_SEARCH_MAX_RESULTS, WEB_SEARCH_TIMEOUT_SECS, BRAVE_API_KEY, and SEARXNG_INSTANCE_URL.

[http_request]

[http_request]
enabled = true
allowed_domains = ["api.example.com", "api.github.com"]
max_response_size = 1000000
timeout_secs = 30
allow_private_hosts = false

Key	Type	Default	Meaning
enabled	bool	false	Enable the http_request tool
allowed_domains	array	["*"]	Allowlist; ["*"] = all public hosts, [] = deny all
max_response_size	integer	1000000	Maximum response size in bytes (1 MB; 0 = unlimited)
timeout_secs	integer	30	Request timeout in seconds
allow_private_hosts	bool	false	Allow requests to private/LAN hosts (SSRF protection when false)

Related pages

• Browser automation — backend setup, agent-browser install, and VNC debugging
• Tools overview — the full agent tool catalog
• Config: channels, tools & integrations — complete config key reference for these tools
• OTP gating & emergency stop — gating browser and web actions behind a one-time password
• Security model — how domain allowlists and SSRF protection fit the broader policy model