| name | vibesurf |
| description | Use when user asks to browse websites, automate browser tasks, fill forms, extract webpage data, search web information, or interact with external apps. This is the main entry point that delegates to detailed reference guides. |
| homepage | https://github.com/vibesurf-ai/VibeSurf |
| metadata | {"moltbot":{"requires":{"env":["VIBESURF_ENDPOINT"]},"primaryEnv":"VIBESURF_ENDPOINT"}} |
VibeSurf - Browser Automation
Control real browsers through VibeSurf. This skill delegates to detailed reference guides.
🚨 VIBESURF STATUS
Check if VibeSurf is running:
curl $VIBESURF_ENDPOINT/health
- ✅ HTTP 200 → Proceed with vibesurf skills
- ❌ Connection refused → Ask user to run
vibesurf (NEVER run it yourself)
Default endpoint: http://127.0.0.1:9335
How to Call VibeSurf API
VibeSurf exposes three core HTTP endpoints:
1. List Available Actions
GET $VIBESURF_ENDPOINT/api/tool/search?keyword={optional_keyword}
Returns all available VibeSurf actions.
2. Get Action Parameters
GET $VIBESURF_ENDPOINT/api/tool/{action_name}/params
Returns JSON schema for the action's parameters.
3. Execute Action
POST $VIBESURF_ENDPOINT/api/tool/execute
Content-Type: application/json
{
"action_name": "action_name_here",
"parameters": {
// action-specific parameters
}
}
Workflow:
- Search for action → Get action name
- Get params schema → See required/optional parameters
- Execute → Call with parameters
⚠️ Parameter Error Handling
ALWAYS call GET /api/tool/{action_name}/params before executing ANY action if you are unsure about parameters.
Which Reference to Read
Configuration References
Note: After configuring Composio or MCP tools, use them through the references/integrations.md (see tool naming: cpo.{toolkit}.{action} or mcp.{server}.{action}).
Decision Flow
Browser/Web Task
│
├─ Need to search for information/bug/issue? → Read [references/search.md](references/search.md) [PREFERRED]
│ Examples: "Search for solutions to [bug name]", "Find latest info about [topic]"
│
├─ Need to fetch URL content directly? → Read [references/fetch.md](references/fetch.md)
│ Examples: "Fetch content from [URL]", "Get documentation at [URL]", "Read this webpage"
│
├─ Need to open website? → Read [references/browser.md](references/browser.md)
│ Examples: "Open documentation site", "Go to [URL]", "Check this page"
│
├─ Need to extract data?
│ ├─ Lists/tables/repeated items? → Read [references/js_code.md](references/js_code.md)
│ └─ Main content? → Read [references/crawl.md](references/crawl.md)
│
├─ Need summary? → Read [references/summary.md](references/summary.md)
│
├─ Stock/finance data? → Read [references/finance.md](references/finance.md)
│
├─ Trending news? → Read [references/trend.md](references/trend.md)
│
├─ Screenshot? → Read [references/screenshot.md](references/screenshot.md)
│
├─ Need precise control or step-by-step operations? → Read [references/browser.md](references/browser.md)
│ Examples: "Click the button", "Type in the field", "Scroll down"
│
├─ Complex task-oriented automation? → Read [references/browser-use.md](references/browser-use.md)
│ Examples: "Fill out this form", "Extract data from multiple pages"
│
├─ Platform API (XiaoHongShu/Youtube/etc)? → Read [references/website-api.md](references/website-api.md)
│
├─ External app (Gmail/Google Calendar/GitHub)? → Read [references/integrations.md](references/integrations.md)
│
├─ Pre-built workflow? → Read [references/workflows.md](references/workflows.md)
│
└─ Need to configure LLM/MCP/VibeSurf/Composio/Schedule/Voice? → Read config-* references
- LLM profiles → [references/config-llm.md](references/config-llm.md)
- MCP servers → [references/config-mcp.md](references/config-mcp.md)
- VibeSurf key/workflows → [references/config-vibesurf.md](references/config-vibesurf.md)
- Composio key/toolkits → [references/config-composio.md](references/config-composio.md)
- Schedule workflows → [references/config-schedule.md](references/config-schedule.md)
- Voice/ASR profiles → [references/config-voice.md](references/config-voice.md)
Quick Reference
Common Patterns
Error Handling
| Error | Solution |
|---|
| VibeSurf not running | Check status: curl $VIBESURF_ENDPOINT/health
If not running: Inform user to run vibesurf
NEVER run the command yourself |
| Don't know which reference | Read decision tables above |
| Action not found | Call GET /api/tool/search to list all actions |
| Wrong parameters | Call GET /api/tool/{action_name}/params to see schema |
| browser-use fails or gets stuck | Fallback to references/browser.md: use get_browser_state → browser.{action} → repeat loop |
| LLM/Crawl/Summary errors | Cause: No LLM profile configured
Solution: Read references/config-llm.md to add an LLM profile first |
| Integration tools empty/not found | Cause: Composio/MCP not configured
Solution: Read references/config-composio.md or references/config-mcp.md to enable toolkits first |
Getting Browser State
🔍 Check Current Browser State
When user asks about current page content or browser status (e.g., "What's on the current page?", "What tabs are open?", "What's the browser showing?"), read references/browser.md and use the get_browser_state action.
This is essential when you don't have context about what the user is currently viewing in their browser.
browser vs browser-use
Both can accomplish the same browser tasks - they're complementary:
| Approach | Best For | How It Works |
|---|
| browser-use (references/browser-use.md) | Complex, long tasks | Task-oriented sub-agent: describe goal + desired output, agent figures out steps |
| browser (references/browser.md) | Precise control | Step-by-step manual control: explicit actions with full visibility |
| Hybrid | Best reliability | Try browser-use first, fallback to browser if it fails |
Fallback pattern when browser-use fails:
browser-use fails or gets stuck
→ Read references/browser.md
→ get_browser_state (inspect page)
→ browser.{action} (perform action)
→ get_browser_state (verify & plan next)
→ repeat until complete
Resources
API Parameter Troubleshooting
If you encounter API parameter errors when calling VibeSurf endpoints, you can visit the interactive API documentation at:
http://127.0.0.1:9335/docs
For example: http://127.0.0.1:9335/docs#/config/create_mcp_profile_api_config_mcp_profiles_post
Note: This is a fallback approach. In most cases, reading the corresponding references/*.md file (e.g., references/config-mcp.md) should provide sufficient guidance on how to use the API correctly. Only refer to the /docs endpoint when the skill documentation doesn't resolve your issue or you need to inspect specific request/response schemas.
