Vibesurf

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:

1. Search for action → Get action name
2. Get params schema → See required/optional parameters
3. 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

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:

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

• GitHub: https://github.com/vibesurf-ai/VibeSurf
• Reference Docs: See references/ folder for detailed guides

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.