zzzgydi/verge-browser

Verge Browser

English | 中文

A browser sandbox platform for AI agents, combining CDP automation, GUI-level screenshots, shared files, and visual human handoff in one isolated runtime.

Sandbox Control | noVNC Session

Core Capabilities

• Real GUI Chromium: not headless; supports multi-tabs, downloads, popups, and full browser behavior
• CDP Automation: compatible with Playwright and Puppeteer through a WebSocket endpoint
• GUI-Level Screenshots: capture the full browser window, not only page content
• Human Handoff: unified session entry for both noVNC and Xpra
• File Sharing: browser and APIs share /workspace for uploads, downloads, and artifacts

Why This Exists

Most browser automation systems focus on headless page control. That is not enough for agent workflows that need to combine:

• browser automation through CDP
• visual reasoning over the full browser window
• human takeover when automation stalls
• shared files inside the same environment

Verge Browser keeps browser, GUI, and files in one isolated sandbox so those workflows remain continuous instead of split across multiple tools.

Agent Skills

This repository now ships built-in skills for AI agents under skills/:

• skills/verge-browser-deploy: deploy Verge Browser, configure env vars, verify health, and troubleshoot startup issues
• skills/verge-browser-usage: operate an already deployed Verge Browser service, manage sandboxes, and combine it with agent-browser

Quick Start

Option 1: Docker Compose (Recommended)

export PROJECT_ROOT="$PWD"
docker compose -f deployments/docker-compose.yml build api runtime-xvfb runtime-xpra
docker compose -f deployments/docker-compose.yml up api

Open http://127.0.0.1:8000/admin to start using.

For local development, sign in with the default admin token dev-admin-token unless you override VERGE_ADMIN_AUTH_TOKEN.

Deployment-related environment variables are documented in docs/env.md.

Option 2: Local Development

Prerequisites:

• Python 3.11+
• Node.js 22+ with Corepack / pnpm
• Docker

1. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Install and build the admin web

corepack enable
pnpm --dir apps/admin-web install --frozen-lockfile
pnpm --dir apps/admin-web build

This emits static files into apps/api-server/app/static/admin.

3. Build the runtime images

docker build -f docker/runtime-xvfb.Dockerfile -t verge-browser-runtime-xvfb:latest .
docker build -f docker/runtime-xpra.Dockerfile -t verge-browser-runtime-xpra:latest .

4. Start the API server

uvicorn app.main:app --app-dir apps/api-server --host 0.0.0.0 --port 8000 --reload

The API is available at http://127.0.0.1:8000, and the admin console is at http://127.0.0.1:8000/admin.

Option 3: Docker Deployment

Run the API server in Docker and let it manage runtime containers through the host Docker socket.

# Build runtime images
docker build -f docker/runtime-xvfb.Dockerfile -t verge-browser-runtime-xvfb:latest .
docker build -f docker/runtime-xpra.Dockerfile -t verge-browser-runtime-xpra:latest .

# Build API server image (also bundles the admin web)
docker build -f docker/api-server.Dockerfile -t verge-browser-api:latest .

# Create a directory for sandbox persistence
mkdir -p .local/sandboxes

# Set non-default auth secrets before exposing the service
export VERGE_ADMIN_AUTH_TOKEN="replace-with-a-long-random-token"
export VERGE_TICKET_SECRET="replace-with-a-long-random-ticket-secret"

# Run the API server container
docker run -d \
  --name verge-api \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd):$(pwd)" \
  -e VERGE_SANDBOX_BASE_DIR="$(pwd)/.local/sandboxes" \
  -e VERGE_ADMIN_AUTH_TOKEN="$VERGE_ADMIN_AUTH_TOKEN" \
  -e VERGE_TICKET_SECRET="$VERGE_TICKET_SECRET" \
  -w "$(pwd)" \
  verge-browser-api:latest

Note: For Linux hosts requiring GPU acceleration, add the appropriate flag to the docker run command so the API container can detect the GPU device:

• Intel / AMD: --device /dev/dri:/dev/dri
• NVIDIA (requires nvidia-container-toolkit on the host): --gpus all

This mode expects the API container to see the same absolute project path as the host so it can mount sandbox workspaces into runtime containers correctly.

For a complete list of deployment env vars, see docs/env.md.

Basic Usage Examples

Install the CLI:

npm install -g verge-browser

Create a sandbox:

verge-browser sandbox create --alias test --width 1440 --height 900

Take a screenshot:

verge-browser browser screenshot test --output ./screenshot.png

Execute GUI actions:

verge-browser browser actions test --input ./actions.json

Get a human handoff URL:

verge-browser sandbox session test

For more commands, see docs/cli-sdk.md.

Development Guide

Admin Web Development

For admin UI development, run Vite separately:

pnpm --dir apps/admin-web dev

The dev server listens on http://127.0.0.1:5173.

Run Tests

Run the full unit suite:

PYTHONPATH=apps/api-server pytest

Run the expected local validation flow for runtime-backed changes:

docker build -f docker/runtime-xvfb.Dockerfile -t verge-browser-runtime-xvfb:latest .
docker build -f docker/runtime-xpra.Dockerfile -t verge-browser-runtime-xpra:latest .
PYTHONPATH=apps/api-server pytest tests/unit tests/integration/test_runtime_api.py

Manual Smoke Scripts

Human-friendly smoke scripts live under tests/scripts.

Common flows:

• tests/scripts/create-sandbox.sh: create a sandbox and print the IDs and follow-up URLs you need
• tests/scripts/get-session-url.sh: create or reuse a sandbox and print a browser-ready session URL
• tests/scripts/browser-smoke.sh: save browser metadata plus window and page screenshots under tests/scripts/.artifacts/
• tests/scripts/files-smoke.sh: exercise the file APIs against /workspace
• tests/scripts/restart-browser.sh: restart Chromium and save browser info before and after
• tests/scripts/full-manual-tour.sh: run the most useful create + screenshot + files + session flow end to end
• tests/scripts/cleanup-sandbox.sh: delete a sandbox when you pass SANDBOX_ID=...

Example:

tests/scripts/full-manual-tour.sh

If your API server is not on http://127.0.0.1:8000, set:

export VERGE_BROWSER_URL="http://127.0.0.1:8000"

Business APIs require the admin bearer token. Set:

export VERGE_BROWSER_TOKEN="<admin-token>"

Cleanup Development Containers

Quick cleanup:

docker ps -aq --filter "label=verge.managed=true" | xargs -r docker rm -f
docker rm -f verge-api 2>/dev/null || true

Full cleanup, including persisted data:

docker ps -aq --filter "label=verge.managed=true" | xargs -r docker rm -f
rm -rf .local/sandboxes

Using Docker Compose:

docker compose -f deployments/docker-compose.yml down
docker compose -f deployments/docker-compose.yml down -v

Development Notes

• The project targets Python 3.11+.
• The API server is implemented with FastAPI.
• WebSocket proxying is designed around CDP and session relay use cases.
• File operations are constrained to the sandbox workspace root.
• Containerized API deployment uses Docker-outside-of-Docker via /var/run/docker.sock.
• The current implementation favors a practical MVP structure over premature multi-tenant orchestration.

API Reference

The current API follows the /sandbox/{sandbox_id}/... routing model.

Detailed endpoint documentation lives in docs/api.md.

SDK and CLI usage examples live in docs/cli-sdk.md.

Scope

Verge Browser focuses on browser control:

• browser lifecycle: create, pause, resume, delete
• browser automation via CDP
• GUI screenshots and input actions
• session-based human takeover with xvfb_vnc or xpra
• file exchange through the sandbox workspace

Arbitrary command execution is intentionally excluded to keep the surface area minimal and the focus narrow.

Project Architecture

System Architecture

At a high level, the platform has two parts:

1. API server Exposes REST and WebSocket endpoints for sandbox lifecycle, browser control, files, CDP proxying, and ticket-based session access.
2. Sandbox runtime Runs Chromium, the desktop stack, and shared /workspace inside one isolated container.

Client / Agent / Human
        |
        v
+------------------------------+
| FastAPI Gateway / API Server |
| Auth + REST + WS + Tickets   |
+------------------------------+
        |
        v
+-----------------------------------------------+
| Sandbox Runtime Container                     |
| xvfb_vnc or xpra + Chromium + /workspace      |
+-----------------------------------------------+

Technical Notes

The platform is functional today for local development and single-node deployment.

The current codebase already includes:

• runtime container boot with Chromium, Xvfb/Openbox or Xpra, and a CDP relay
• sandbox creation through the API
• persisted sandbox metadata with startup recovery into STOPPED
• pause and resume lifecycle for reusing an existing workspace
• real window screenshots
• page screenshots through CDP
• GUI action execution through xdotool
• ticket-based session entry for noVNC and Xpra
• workspace-scoped file list, read, write, upload, download, and delete operations
• an admin web console built into static assets and served by the API at /admin
• runtime Dockerfiles, supervisor configuration, startup scripts, and Docker-backed integration coverage

Current hardening work is focused on:

• stronger Docker lifecycle management and health-driven state transitions
• production-ready browser crash recovery and degraded-state handling
• file and browser integration coverage
• broader end-to-end and failure-mode coverage

Repository Layout

apps/
  api-server/         FastAPI application
  admin-web/          Vite + React admin console, built into API static assets
  runtime-xvfb/       Xvfb + VNC runtime assets
  runtime-xpra/       Xpra runtime assets
deployments/          Local deployment assets
docker/               Runtime and API container build files
tests/                Unit and integration tests
docs/                 Product, API, and technical docs

Runtime Images

The runtime images host:

• Chromium
• xdotool
• supervisor
• a small TCP relay so the platform can expose a stable CDP entrypoint even though Chromium itself listens on an internal debugging port

Two runtime variants are supported:

• xvfb_vnc: Xvfb + Openbox + x11vnc + noVNC / websockify
• xpra: Xpra server + HTML5 client assets

Desktop Options Comparison

How to choose:

• Mostly automation, with occasional human inspection: use xvfb_vnc
• Frequent manual intervention or remote debugging: use xpra

License

The original source code in this repository is licensed under the MIT License. See LICENSE.

Built runtime artifacts may include third-party software under separate licenses. In particular, the runtime-xpra image installs Xpra, which is licensed under GPL v2 or later and remains subject to its own license terms.

See THIRD_PARTY_NOTICES.md and docs/open-source-compliance.md before distributing container images externally.