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

• 🔄 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.

🎯 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!

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.

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"

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].

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.

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

# 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).

# 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

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

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

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 .

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/

Option 1: Direct Server

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

Option 2: CLI Entry

uv run vibesurf

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

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

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

• Browser Use
• LangGraph
• Langflow

Huge thanks to their creators and contributors!

Welcome to join our WeChat group for discussions!