Skip to main content

​
Browser Sandbox

The browser sandbox lets agents browse the web in a controlled, auditable environment.

​
Configuration

Go to Settings → Advanced to configure:
SettingDefaultDescription
HeadlessOnRun browser without visible window
Auto-close tabsOnClose tabs after agent finishes
Idle timeout300sKill browser after inactivity

​
Profiles

Create isolated browser profiles for different purposes:
  • Each profile has its own cookies, storage, and history
  • Agents can switch between profiles
  • Prevents cross-contamination between tasks

​
Network policy

Control which domains agents can access:

​
Default allowed domains

DomainPurpose
api.openai.comAI provider
api.anthropic.comAI provider
generativelanguage.googleapis.comAI provider
openrouter.aiAI provider
api.elevenlabs.ioTTS provider
duckduckgo.comWeb search
html.duckduckgo.comWeb search
api.coinbase.comTrading
localhostLocal services

​
Default blocked domains

DomainReason
pastebin.comData exfiltration risk
transfer.shFile sharing risk
file.ioFile sharing risk
0x0.stAnonymous upload risk

​
Custom rules

Add your own allowed or blocked domains in the browser settings. Blocked domains take priority over allowed.

​
Request logging

Enable log requests to see all network requests the browser makes. Recent requests are shown in the settings panel for auditing.

​
Agent tools

ToolDescription
web_browseNavigate to a URL and interact with the page
web_screenshotCapture a screenshot of the current page
web_readExtract text content from a page

​
Browser sandbox architecture

The browser sandbox uses headless Chromium via the headless_chrome Rust crate (Chrome DevTools Protocol):
  • Lazy initialization — Chrome is only launched when an agent first calls web_screenshot or web_browse
  • Singleton instance — one shared browser process with health checks; auto-relaunches if Chrome dies
  • Session continuity — web_browse reuses the first tab for multi-step interactions within a session
  • Idle timeout — configurable (default 300s), kills Chrome after inactivity

​
Screenshot capture and vision analysis

The web_screenshot tool captures full-page screenshots and extracts visible text:
ParameterDefaultDescription
url(required)Page to capture
full_pagefalseCapture entire scrollable page
width1280Viewport width in pixels
height800Viewport height in pixels
Screenshots are:
  1. Saved as PNG to $TMPDIR/paw-screenshots/screenshot-YYYYMMDD-HHMMSS.png
  2. Accompanied by extracted visible text (up to 5000 chars) so the agent can “read” the page
  3. Viewable in Settings → Advanced screenshot gallery
:::tip When web_read returns empty text (JavaScript-rendered pages), use web_screenshot instead — it waits for dynamic content to load and extracts visible text from the rendered DOM. :::

​
Form filling and interaction

The web_browse tool supports full page interaction:
ActionParametersDescription
navigate / gotourlNavigate to a URL and wait for load
clickselectorClick an element by CSS selector
type / fillselector, textClick an input and type text into it
presstext (key name)Press a keyboard key (Enter, Tab, etc.)
extract / readselector (optional)Extract text content from elements
javascript / eval / jsjavascriptExecute arbitrary JavaScript
scrolltext (up/down/top/bottom)Scroll the page
links—List all links on the page (up to 50)
info—Get current page title and URL

​
Example: filling a login form

The agent can chain multiple web_browse calls: 
1. web_browse(action: "navigate", url: "https://example.com/login")
2. web_browse(action: "type", selector: "#email", text: "user@example.com")
3. web_browse(action: "type", selector: "#password", text: "...")
4. web_browse(action: "click", selector: "button[type=submit]")
Browser profiles provide isolated cookie and session storage:
FeatureDescription
Profile directoryEach profile stores cookies, localStorage, and cache in ~/.paw/browser-profiles/<profile-id>/
Session persistenceCookies and logged-in sessions survive across agent tool calls within the same profile
Profile isolationDifferent profiles have completely separate storage — no cross-contamination
Profile switchingSet the default profile in Settings → Advanced

​
Managing profiles

  • Create — go to Settings → Advanced → Browser → “New Profile”
  • Delete — removes the profile directory and all associated data
  • Set default — choose which profile new browser sessions use

​
Proxy support

Proxy configuration can be applied through Chrome launch flags. Set the HTTP_PROXY or HTTPS_PROXY environment variables before launching Pawz, and the headless Chrome instance will respect them.

​
Security

  • Network policy is enforced at the browser level — agents cannot bypass it
  • All browser activity is contained within the profile
  • Headless mode prevents agents from displaying arbitrary content
  • Idle timeout prevents runaway browser sessions