VibeSurf: A powerful browser assistant for vibe surfing

Note: VibeSurf can be used in Claude Code for control and real-time preview of browsers. For more details, see the claude-surf.

Note: VibeSurf is also available in Open-Claw. Install with: npx clawhub@latest install vibesurf. For more details, see claw-surf.

VibeSurf is the first open-source AI agentic browser that combines workflow automation with intelligent AI agents - delivering browser automation that's faster, cheaper, and smarter than traditional solutions.

🎯 Why VibeSurf? Save 99% of token costs with workflows, run parallel AI agents across tabs, and keep your data private with local LLM support - all through a seamless Chrome extension.

🐳 Quick Start with Docker: Get up and running in seconds with our Docker image - no complex setup required!

☁️ Non-Docker Deployment: For cloud manual deployment with noVNC browser visualization, see docs/cloud-manual-start.md.

If you're as excited about open-source AI browsing as I am, give it a star! ⭐

中文 | English

✨ Key Features

• 🔄 Revolutionary Browser Workflows: Create drag-and-drop workflows that consume virtually zero tokens - define once, run forever. Perfect for auto-login, data collection, and repetitive tasks with 100x speed boost.

• 🚀 Multi-Agent Parallel Processing: Run multiple AI agents simultaneously across different browser tabs for massive efficiency gains in both deep and wide research.

• 🧠 Intelligent AI Automation: Beyond basic automation - perform deep research, intelligent crawling, content summarization, and adaptive browsing with AI decision-making.

• 🔒 Privacy-First Architecture: Full support for local LLMs (Ollama, etc.) and custom APIs - your browsing data never leaves your machine during vibe surfing.

• 🎨 Seamless Chrome Extension: Native browser integration without switching applications - feels like a natural part of your browser with intuitive UI.

• 🐳 One-Click Docker Deployment: Get started instantly with our Docker image - includes VNC access for remote browsing and easy scaling.

🚀 Browser Workflow Magic

Why Browser Workflow Matters

🎯 Efficiency First: Most browser operations follow predictable patterns - why rebuild them every time with agents? Workflows let you define once, run forever.

💰 Token Savings: Workflows consume virtually zero tokens, only using them when dynamic information retrieval is needed. Save costs while maintaining intelligence.

⚡ Speed & Reliability: Deterministic workflows deliver consistent, fast, and highly accurate results. No more waiting for agents to "think" through repetitive steps.

A tutorial that step-by-step guides you from scratch on using VibeSurf to build a browser automation workflow that searches X and extracts results. Beyond the basics, it demonstrates how to transform this workflow into a deployable API and integrate it as a custom Skill within Claude Code.

👉 Explore Workflow Templates - Get started with pre-built workflows for common tasks!

🛠️ Installation

For Windows users: You can also download and run our one-click installer: VibeSurf-Installer.exe

Note: If you encounter DLL errors related to torch c10.so or onnxruntime during installation, please download and install the Microsoft Visual C++ Redistributable.

Get VibeSurf up and running in just three simple steps. No complex configuration required.

1. Install uv

Install uv package manager from the official website

MacOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install VibeSurf

Install VibeSurf as a tool

uv tool install vibesurf

Tip: Use uv tool upgrade vibesurf to upgrade to the latest version.

Full Installation: To install with all optional features (including PyTorch, OCR, and advanced document processing), use uv tool install vibesurf[full].

3. Launch VibeSurf

Start the VibeSurf browser assistant

vibesurf

Note: To run in headless browser mode without a visible GUI, use the --headless flag:

vibesurf --headless

Note: Starting from Chrome 142, the --load-extension flag is no longer supported. When you first start VibeSurf, the browser will show a popup displaying the extension path. To manually load the extension:

• Open chrome://extensions
• Enable Developer mode
• Click "Load unpacked" and navigate to the extension folder

Typical Extension Locations:

• Windows: C:\Users\<username>\AppData\Roaming\uv\tools\vibesurf\Lib\site-packages\vibe_surf\chrome_extension

• macOS: ~/.local/share/uv/tools/vibesurf/lib/python3.<version>/site-packages/vibe_surf/chrome_extension (replace <version> with your Python version, e.g., python3.12)

  Tip: Besides the popup, you can also find the extension path in the command line startup logs. For macOS users, press Cmd+Shift+G in Finder, paste the path, and press Enter to navigate directly to the folder.

4. Start to Use

Your browser does not support playing this video!

🐳 Docker (Alternative)

You can also run VibeSurf in Docker with browser VNC access:

Option 1: Using docker-compose (Recommended)

# 1. Clone VibeSurf Repo
git clone https://github.com/vibesurf-ai/VibeSurf
cd VibeSurf
# Optional: Edit docker-compose.yml to modify envs

# 2. Start VibeSurf
docker-compose up -d

# 3. Access VibeSurf
# - Backend: http://localhost:9335
# - Browser VNC (Web): http://localhost:6080 (default password: vibesurf)

Note: The VNC browser environment defaults to English input. Press Ctrl + Space to switch to Chinese Pinyin input method.

Note: To use a proxy, set the HTTP_PROXY and HTTPS_PROXY environment variables in docker-compose.yml (e.g., HTTP_PROXY: http://proxy.example.com:8080).

Option 2: Using docker run

# Pull the image
docker pull ghcr.io/vibesurf-ai/vibesurf:latest

# Run the container
docker run --name vibesurf -d --restart unless-stopped \
  -p 9335:9335 \
  -p 6080:6080 \
  -p 5901:5901 \
  -v ./data:/data \
  -e IN_DOCKER=true \
  -e VIBESURF_BACKEND_PORT=9335 \
  -e VIBESURF_WORKSPACE=/data/vibesurf_workspace \
  -e RESOLUTION=1440x900x24 \
  -e VNC_PASSWORD=vibesurf \
  --shm-size=4g \
  --cap-add=SYS_ADMIN \
  ghcr.io/vibesurf-ai/vibesurf:latest

👩‍💻 For Contributors

Want to contribute to VibeSurf? Follow these steps to set up your development environment:

1. Clone Repository

git clone https://github.com/vibesurf-ai/VibeSurf.git
cd VibeSurf

2. Setup Environment

MacOS/Linux

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

Full Installation (with all optional features)

uv pip install -e ".[full]"

Windows

uv venv --python 3.12
.venv\Scripts\activate
uv pip install -e .

3. Build Frontend (Optional)

If you're working on frontend changes, you need to build and copy the frontend to the backend directory:

# Navigate to frontend directory
cd vibe_surf/frontend

# Install frontend dependencies
npm ci

# Build the frontend
npm run build

# Copy build output to backend directory
mkdir -p ../backend/frontend
cp -r build/* ../backend/frontend/

4. Start Debugging

Option 1: Direct Server

uvicorn vibe_surf.backend.main:app --host 127.0.0.1 --port 9335

Option 2: CLI Entry

uv run vibesurf

🗺️ Roadmap

We're building VibeSurf to be your ultimate AI browser companion. Here's what's coming next:

• Smart Skills System - Completed Add /search for quick information search, /crawl for automatic website data extraction and /code for webpage js code execution. Integrated native APIs for Xiaohongshu, Douyin, Weibo, and YouTube.

• Third-Party Integrations - Completed Connect with hundreds of popular tools including Gmail, Notion, Google Calendar, Slack, Trello, GitHub, and more through Composio integration to combine browsing with powerful automation capabilities

• Agentic Browser Workflow - Completed Create custom drag-and-drop and conversation-based workflows for auto-login, data collection, and complex browser automation tasks

• Powerful Coding Agent - In Progress Build a comprehensive coding assistant for data processing and analysis directly in your browser

• Intelligent Memory & Personalization - Planned Transform VibeSurf into a truly human-like companion with persistent memory that learns your preferences, habits, and browsing patterns over time

🎬 Demo

How to use?

Your browser does not support playing this video!

Dozens of agent running in on browser

Your browser does not support playing this video!

📝 License

This repository is licensed under the VibeSurf Open Source License, based on Apache 2.0 with additional conditions.

👏 Acknowledgments

VibeSurf builds on top of other awesome open-source projects:

• Browser Use
• LangGraph
• Langflow

Huge thanks to their creators and contributors!

💬 Join Our Community

Welcome to join our WeChat group for discussions!