Metadata-Version: 2.4
Name: vibesurf
Version: 0.5.13
Summary: VibeSurf: A powerful browser assistant for vibe surfing
Author: WarmShao
License: Apache-2.0
Project-URL: Repository, https://github.com/vibesurf-ai/VibeSurf
Keywords: browser use,browser automation,browser assistant,agentic browser,vibe surf,AI browser
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: uuid7>=0.1.0
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: anyio>=4.9.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: cdp-use>=1.4.1
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: scikit-image>=0.25.2
Requires-Dist: python-socks>=2.7.2
Requires-Dist: langgraph>=0.6.4
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: websockets>=12.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: rich>=13.0.0
Requires-Dist: greenlet>=3.2.4
Requires-Dist: getmac>=0.9.5
Requires-Dist: markdown-pdf>=1.9
Requires-Dist: nanoid>=2.0.0
Requires-Dist: markdownify>=1.2.0
Requires-Dist: pathvalidate>=3.3.1
Requires-Dist: dashscope>=1.24.5
Requires-Dist: pyexecjs>=1.5.1
Requires-Dist: browser-use==0.9.5
Requires-Dist: google-genai<2.0.0,>=1.52.0
Requires-Dist: openai<2.0.0,>=1.99.2
Requires-Dist: google-api-python-client>=2.174.0
Requires-Dist: google-auth>=2.40.3
Requires-Dist: google-auth-oauthlib>=1.2.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.11.5
Requires-Dist: pypdf>=5.7.0
Requires-Dist: authlib>=1.6.0
Requires-Dist: websockets>=15.0.1
Requires-Dist: json-repair>=0.48.0
Requires-Dist: yfinance>=0.2.66
Requires-Dist: croniter>=6.0.0
Requires-Dist: xhshow>=0.1.5
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: seaborn>=0.13.2
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: parsel==1.10.0
Requires-Dist: curl_cffi<0.14.0,>=0.13.0
Requires-Dist: celery>=5.5.3
Requires-Dist: fastapi==0.116.1
Requires-Dist: httpx[http2]<1.0.0,>=0.27
Requires-Dist: aiofile<4.0.0,>=3.9.0
Requires-Dist: uvicorn<1.0.0,>=0.30.0
Requires-Dist: gunicorn<24.0.0,>=22.0.0
Requires-Dist: langchain~=0.3.21
Requires-Dist: langchain-community~=0.3.20
Requires-Dist: langchain-core~=0.3.45
Requires-Dist: langchainhub~=0.1.15
Requires-Dist: loguru<1.0.0,>=0.7.1
Requires-Dist: structlog>=25.4.0
Requires-Dist: rich>=14.0.0
Requires-Dist: langchain-experimental<1.0.0,>=0.3.4
Requires-Dist: sqlmodel==0.0.22
Requires-Dist: pydantic>=2.10.1
Requires-Dist: pydantic-settings<3.0.0,>=2.2.0
Requires-Dist: typer<1.0.0,>=0.13.0
Requires-Dist: cachetools<6.0.0,>=5.5.0
Requires-Dist: platformdirs<5.0.0,>=4.2.0
Requires-Dist: python-multipart<1.0.0,>=0.0.12
Requires-Dist: orjson==3.10.15
Requires-Dist: alembic<2.0.0,>=1.13.0
Requires-Dist: passlib<2.0.0,>=1.7.4
Requires-Dist: bcrypt==4.0.1
Requires-Dist: pillow<12.0.0,>=11.1.0
Requires-Dist: docstring-parser<1.0.0,>=0.16
Requires-Dist: python-jose<4.0.0,>=3.3.0
Requires-Dist: pandas==2.2.3
Requires-Dist: multiprocess<1.0.0,>=0.70.14
Requires-Dist: python-docx<2.0.0,>=1.1.0
Requires-Dist: jq<2.0.0,>=1.7.0; sys_platform != "win32"
Requires-Dist: nest-asyncio<2.0.0,>=1.6.0
Requires-Dist: emoji<3.0.0,>=2.12.0
Requires-Dist: cryptography<44.0.0,>=42.0.5
Requires-Dist: asyncer<1.0.0,>=0.0.5
Requires-Dist: pyperclip<2.0.0,>=1.8.2
Requires-Dist: uncurl<1.0.0,>=0.0.11
Requires-Dist: sentry-sdk[fastapi,loguru]<3.0.0,>=2.5.1
Requires-Dist: chardet<6.0.0,>=5.2.0
Requires-Dist: firecrawl-py<2.0.0,>=1.0.16
Requires-Dist: opentelemetry-api<2.0.0,>=1.25.0
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.25.0
Requires-Dist: opentelemetry-exporter-prometheus<1.0.0,>=0.46b0
Requires-Dist: opentelemetry-instrumentation-fastapi<1.0.0,>=0.46b0
Requires-Dist: prometheus-client<1.0.0,>=0.20.0
Requires-Dist: aiofiles<25.0.0,>=24.1.0
Requires-Dist: setuptools<79.0.0,>=78.1.0
Requires-Dist: nanoid<3.0.0,>=2.0.0
Requires-Dist: filelock<4.0.0,>=3.15.4
Requires-Dist: grandalf<1.0.0,>=0.8.0
Requires-Dist: spider-client<1.0.0,>=0.0.27
Requires-Dist: diskcache<6.0.0,>=5.6.3
Requires-Dist: clickhouse-connect==0.7.19
Requires-Dist: fastapi-pagination<1.0.0,>=0.13.1
Requires-Dist: defusedxml<1.0.0,>=0.7.1
Requires-Dist: pypdf>=5.1.0
Requires-Dist: validators>=0.34.0
Requires-Dist: networkx>=3.4.2
Requires-Dist: json-repair>=0.30.3
Requires-Dist: mcp~=1.10.1
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: greenlet>=3.1.1
Requires-Dist: jsonquerylang>=1.1.1
Requires-Dist: elevenlabs==1.58.1; python_version == "3.12"
Requires-Dist: elevenlabs>=1.52.0; python_version != "3.12"
Requires-Dist: scipy>=1.15.2
Requires-Dist: trustcall>=0.0.38
Requires-Dist: langchain-chroma>=0.1.4
Requires-Dist: beautifulsoup4==4.12.3
Requires-Dist: google-search-results<3.0.0,>=2.4.1
Requires-Dist: google-api-python-client>=2.154.0
Requires-Dist: huggingface-hub[inference]<1.0.0,>=0.23.2
Requires-Dist: networkx==3.4.2
Requires-Dist: fake-useragent==1.5.1
Requires-Dist: pyarrow==19.0.0
Requires-Dist: types-cachetools<6.0.0,>=5.5.0.20240820
Requires-Dist: supabase<3.0.0,>=2.6.0
Requires-Dist: certifi<2025.0.0,>=2023.11.17
Requires-Dist: metaphor-python==0.1.23
Requires-Dist: pywin32==307; sys_platform == "win32"
Requires-Dist: langfuse==2.53.9
Requires-Dist: MarkupSafe==3.0.2
Requires-Dist: boto3<2.0.0,>=1.34.162
Requires-Dist: numexpr==2.10.2
Requires-Dist: langchain==0.3.23
Requires-Dist: pytube==15.0.0
Requires-Dist: datasets<4.0.0,>2.14.7
Requires-Dist: litellm<2.0.0,>=1.60.2
Requires-Dist: youtube-transcript-api>=1.2.3
Requires-Dist: Markdown==3.7
Requires-Dist: GitPython==3.1.43
Requires-Dist: langsmith<1.0.0,>=0.3.42
Requires-Dist: yfinance>=0.2.50
Requires-Dist: composio==0.8.20
Requires-Dist: composio-langchain==0.8.20
Requires-Dist: nltk==3.9.1
Requires-Dist: lark==1.2.2
Requires-Dist: jq==1.8.0
Requires-Dist: pydantic-settings<3.0.0,>=2.2.0
Requires-Dist: duckduckgo_search==7.2.1
Requires-Dist: opensearch-py==2.8.0
Requires-Dist: langchain-google-genai>=2.0.6
Requires-Dist: langchain-cohere==0.3.3
Requires-Dist: langchain-huggingface==0.3.1
Requires-Dist: langchain-anthropic==0.3.14
Requires-Dist: langchain-astradb<1.0.0,>=0.6.1
Requires-Dist: langchain-openai<1.0.0,>=0.2.12
Requires-Dist: langchain-google-vertexai<3.0.0,>=2.0.7
Requires-Dist: langchain-groq==0.2.1
Requires-Dist: langchain-pinecone<1.0.0,>=0.2.8
Requires-Dist: langchain-mistralai==0.2.3
Requires-Dist: langchain-chroma<1.0.0,>=0.2.6
Requires-Dist: langchain-aws==0.2.33
Requires-Dist: langchain-unstructured==0.1.5
Requires-Dist: langchain-milvus==0.1.7
Requires-Dist: langchain-mongodb==0.7.0
Requires-Dist: langchain-nvidia-ai-endpoints==0.3.8
Requires-Dist: langchain-google-calendar-tools==0.0.1
Requires-Dist: langchain-google-community==2.0.3
Requires-Dist: langchain-elasticsearch==0.3.0
Requires-Dist: langchain-ollama==0.2.1
Requires-Dist: langchain-sambanova==0.1.0
Requires-Dist: langchain-community<1.0.0,>=0.3.21
Requires-Dist: sqlalchemy[aiosqlite]<3.0.0,>=2.0.38
Requires-Dist: needle-python<1.0.0,>=0.4.0
Requires-Dist: aiofile<4.0.0,>=3.9.0
Requires-Dist: mcp<2.0.0,>=1.10.1
Requires-Dist: scipy<1.16.2,>=1.14.1
Requires-Dist: pydantic-ai<1.0.0,>=0.0.19
Requires-Dist: langchain-graph-retriever==0.8.0
Requires-Dist: graph-retriever==0.8.0
Requires-Dist: gassist>=0.0.1; sys_platform == "win32"
Requires-Dist: filelock<4.0.0,>=3.18.0
Requires-Dist: structlog<26.0.0,>=25.4.0
Requires-Dist: cryptography<44.0.0,>=43.0.1
Requires-Dist: aiosqlite==0.21.0
Requires-Dist: fastparquet<2025.0.0,>=2024.11.0
Requires-Dist: traceloop-sdk<1.0.0,>=0.43.1
Requires-Dist: docling_core>=2.36.1
Requires-Dist: pytest-codspeed==4.0.0
Provides-Extra: full
Requires-Dist: torch<2.3.0,>=2.0.0; (sys_platform == "darwin" and platform_machine == "x86_64") and extra == "full"
Requires-Dist: torch>=2.3.0; (sys_platform != "darwin" or platform_machine != "x86_64") and extra == "full"
Requires-Dist: docling>=2.36.1; (sys_platform != "darwin" or platform_machine != "x86_64") and extra == "full"
Requires-Dist: easyocr>=1.7.2; (sys_platform != "darwin" or platform_machine != "x86_64") and extra == "full"
Requires-Dist: opencv-python>=4.11; (sys_platform != "darwin" or platform_machine != "x86_64") and extra == "full"
Requires-Dist: silero-vad==6.2.0; extra == "full"
Requires-Dist: srt==3.5.3; extra == "full"
Requires-Dist: soundfile==0.13.1; extra == "full"
Requires-Dist: pydub==0.25.1; extra == "full"
Requires-Dist: ffmpeg-python>=0.2.0; extra == "full"
Dynamic: license-file

# VibeSurf: A powerful browser assistant for vibe surfing
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/86SPfhRVbk)
[![WeChat](https://img.shields.io/badge/WeChat-Group-07C160?logo=wechat&logoColor=white)](#-join-our-community)
[![WarmShao](https://img.shields.io/twitter/follow/warmshao?style=social)](https://x.com/warmshao)

> **Note**: VibeSurf can be used in Claude Code for control and real-time preview of browsers. For more details, see the [claude-surf plugin](https://github.com/vibesurf-ai/claude-surf).
>
> **Note**: VibeSurf is also available in Open-Claw. Install with: `npx clawhub@latest install vibesurf`. For more details, see [claw-surf](https://github.com/vibesurf-ai/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](#-docker-alternative) - no complex setup required!

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

[中文](README_zh.md) | [English](README.md)

## ✨ 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](#-docker-alternative) - 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.

[![Tutorial: Build Browser Automation Workflow and Deploy as API](https://img.youtube.com/vi/N9VMzLMKKpk/maxresdefault.jpg)](https://www.youtube.com/watch?v=N9VMzLMKKpk)

*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**](https://vibe-surf.com/workflows) - 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](https://github.com/vibesurf-ai/VibeSurf/releases/latest/download/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](https://aka.ms/vc14/vc_redist.x64.exe).

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**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### 2. Install VibeSurf
Install VibeSurf as a tool

```bash
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

```bash
vibesurf
```

**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

<video src="https://github.com/user-attachments/assets/86dba2e4-3f33-4ccf-b400-d07cf1a481a0" controls="controls">Your browser does not support playing this video!</video>

## 🐳 Docker (Alternative)

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

### Option 1: Using docker-compose (Recommended)

```bash
# 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

```bash
# 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
```bash
git clone https://github.com/vibesurf-ai/VibeSurf.git
cd VibeSurf
```

### 2. Setup Environment
**MacOS/Linux**
```bash
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .
```

**Full Installation (with all optional features)**
```bash
uv pip install -e ".[full]"
```

**Windows**
```bash
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:

```bash
# 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**
```bash
uvicorn vibe_surf.backend.main:app --host 127.0.0.1 --port 9335
```

**Option 2: CLI Entry**
```bash
uv run vibesurf
```
## 🗺️ Roadmap

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

- [x] **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.

- [x] **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

- [x] **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?
<video src="https://github.com/user-attachments/assets/0a4650c0-c4ed-423e-9e16-7889e9f9816d" controls="controls">Your browser does not support playing this video!</video>

### Dozens of agent running in on browser
<video src="https://github.com/user-attachments/assets/9c461a6e-5d97-4335-ba09-59e8ec4ad47b" controls="controls">Your browser does not support playing this video!</video>


## 📝 License

This repository is licensed under the [VibeSurf Open Source License](./LICENSE), based on Apache 2.0 with additional conditions.

## 👏 Acknowledgments

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

- [Browser Use](https://github.com/browser-use/browser-use)
- [LangGraph](https://github.com/langchain-ai/langgraph)
- [Langflow](https://github.com/langflow-ai/langflow)

Huge thanks to their creators and contributors!



## 💬 Join Our Community

Welcome to join our WeChat group for discussions!

<img src="./vibe_surf/chrome_extension/icons/wx.png" width="300" alt="WeChat Group">
