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:

​
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

​
Default blocked domains

​
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

​
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: 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:

​
Example: filling a login form

The agent can chain multiple web_browse calls:
Browser profiles provide isolated cookie and session storage:

​
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