stagehand-plus

A REST API server that wraps Stagehand for AI-driven browser automation, with built-in Tavily web search and FireCrawl web scraping.

One server. Three capabilities:

• Browser automation — Navigate, click, extract, and run full agent workflows via Stagehand
• Web search — Find URLs and answers before navigating (Tavily)
• Web scraping — Extract structured data without spinning up a browser (FireCrawl)

Quick Start

# Install globally
npm install -g stagehand-plus

# Generate global config file
stagehand-plus --init
# → creates ~/.stagehand-plus/settings.json

# Edit your API keys
vim ~/.stagehand-plus/settings.json

# Start the server
stagehand-plus
# → listening on http://localhost:9090

Or use npx without installing:

npx stagehand-plus

CLI Commands

stagehand-plus              # Start the server
stagehand-plus --stop       # Stop the running server
stagehand-plus --init       # Generate ~/.stagehand-plus/settings.json
stagehand-plus --version    # Show current version + check for updates
stagehand-plus --update     # Self-update to latest version

Configuration

Global config (recommended)

Run stagehand-plus --init to create ~/.stagehand-plus/settings.json:

{
  "port": 9090,
  "modelName": "gpt-4o",
  "modelApiKey": "sk-...",
  "tavilyApiKey": "tvly-...",
  "firecrawlApiKey": "fc-..."
}

Set once, works everywhere. No need to create .env in every directory.

Per-project .env (optional override)

If you need different keys for a specific project, create a .env in that directory:

MODEL_API_KEY=sk-different-key

Priority order (highest to lowest)

1. Per-request headers — x-model-api-key, x-tavily-api-key, x-firecrawl-api-key
2. .env file — in the current working directory
3. ~/.stagehand-plus/settings.json — global config
4. Environment variables — export MODEL_API_KEY=sk-...

API Reference

Health Check

GET /health

{ "status": "ok", "activeSessions": 0, "uptime": 123.45 }

---

Browser Automation (Session-based)

All browser endpoints require a session. Start one first, then use the session ID.

Start Session

POST /v1/sessions/start
Header: x-model-api-key (optional, overrides env)

{
  "modelName": "gpt-4o",
  "systemPrompt": "You are a helpful browser assistant",
  "domSettleTimeoutMs": 3000,
  "selfHeal": true
}

Response:

{
  "success": true,
  "data": { "available": true, "sessionId": "uuid-here" }
}

Navigate

POST /v1/sessions/:sessionId/navigate

{
  "url": "https://example.com",
  "options": { "waitUntil": "load", "timeout": 30000 }
}

Act

Perform an action described in natural language.

POST /v1/sessions/:sessionId/act

{
  "input": "Click the Sign In button",
  "options": { "timeout": 10000 }
}

Observe

Find interactive elements on the page.

POST /v1/sessions/:sessionId/observe

{
  "instruction": "Find all navigation links"
}

Extract

Extract data from the current page.

POST /v1/sessions/:sessionId/extract

{
  "instruction": "Extract all product names and prices",
  "schema": {
    "type": "object",
    "properties": {
      "products": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "string" }
          }
        }
      }
    }
  }
}

Agent Execute

Run a multi-step agent that autonomously completes a task.

POST /v1/sessions/:sessionId/agentExecute

{
  "executeOptions": {
    "instruction": "Go to Hacker News and find the top 3 stories",
    "maxSteps": 10
  },
  "agentConfig": {
    "model": "gpt-4o"
  }
}

End Session

POST /v1/sessions/:sessionId/end

---

Web Search (No session needed)

POST /v1/search
Header: x-tavily-api-key (optional, overrides env)

{
  "query": "best practices for browser automation",
  "maxResults": 5,
  "searchDepth": "basic",
  "topic": "general",
  "includeAnswer": true,
  "timeRange": "month"
}

Parameter	Type	Default	Description
query	string	required	Search query
maxResults	number	5	Number of results (1-20)
searchDepth	"basic" | "advanced"	"basic"	Search depth
topic	"general" | "news" | "finance"	"general"	Search category
includeAnswer	boolean	false	Include AI-generated answer
includeRawContent	boolean	false	Include full page content
includeDomains	string[]	[]	Restrict to these domains
excludeDomains	string[]	[]	Exclude these domains
timeRange	"day" | "week" | "month" | "year"	—	Time filter

---

Web Scraping (No session needed)

POST /v1/scrape
Header: x-firecrawl-api-key (optional, overrides env)

{
  "url": "https://example.com/article",
  "formats": ["markdown"],
  "onlyMainContent": true,
  "waitFor": 5000
}

Parameter	Type	Default	Description
url	string	required	URL to scrape
formats	string[]	["markdown"]	"markdown", "html", "rawHtml", "links", "json"
onlyMainContent	boolean	true	Strip navs, footers, ads
includeTags	string[]	—	CSS selectors to include
excludeTags	string[]	—	CSS selectors to exclude
waitFor	number	0	Ms to wait for JS rendering
timeout	number	30000	Request timeout in ms
mobile	boolean	false	Emulate mobile device
jsonOptions	object	—	{ prompt, schema } for structured extraction

Development

git clone https://github.com/ryan941/stagehand-plus.git
cd stagehand-plus
npm install
cp .env.example .env
# Fill in your API keys in .env

npm run dev    # Development with hot reload
npm run build  # Compile TypeScript
npm start      # Run compiled version

Architecture

src/
  index.ts              Express server + graceful shutdown
  session-manager.ts    Stagehand session lifecycle (create/get/end)
  routes/
    health.ts           GET  /health
    sessions.ts         POST /v1/sessions/* (browser automation)
    search.ts           POST /v1/search (Tavily web search)
    scrape.ts           POST /v1/scrape (FireCrawl web scraping)

License

MIT