Skip to content

Commit fdbb58c

Browse files
monadoidmonadoid
authored
Add fastify server (#1384)
# why Stand up a Fastify Stagehand server we can reuse for thin-client SDKs across multiple languages. # what changed created new fastify server # test Plan - Start the Fastify server (pnpm --filter server dev or your usual command). - Local browser smoke: MODEL_API_KEY=... ./scripts/test_local_browser.sh - Browserbase smoke: MODEL_API_KEY=... BROWSERBASE_API_KEY=... BROWSERBASE_PROJECT_ID=... ./scripts/test_remote_browser.sh. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Adds a new Fastify-based Stagehand API server exposing V3 browser automation over REST with streaming responses and session management. Supports both local Chrome and Browserbase, includes health/readiness endpoints, and ships an OpenAPI spec. - **New Features** - New packages/server with REST routes: start, navigate, observe, act, extract, agentExecute, end (streaming logs/results) - In-memory LRU session store with TTL, lazy V3 init, and cleanup on end - Local and Browserbase browsers; credentials passed via headers - Health (/healthz) and readiness (/readyz), metrics, and structured request logging - OpenAPI v3 spec and README - Removed v2 code and DB dependency; auth currently disabled - **Migration** - Run: pnpm --filter @browserbasehq/stagehand-server dev - Required header: x-model-api-key; for Browserbase also x-bb-api-key and x-bb-project-id <sup>Written for commit ed1089b. Summary will update automatically on new commits.</sup> <!-- End of auto-generated description by cubic. -->
1 parent 75f87f1 commit fdbb58c

34 files changed

+3568
-100
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,8 +176,8 @@ jobs:
176176
with:
177177
name: build-artifacts
178178
path: |
179-
packages/*/dist/
180-
packages/*/lib/
179+
packages/core/dist/**
180+
packages/core/lib/**
181181
retention-days: 1
182182

183183
- name: Run Vitest

‎packages/server/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Stagehand API
2+
3+
The Stagehand is a powerful service that provides a RESTful interface for browser automation and session management using the Browserbase platform. It enables recording, playback, and manipulation of browser sessions with a focus on reliability and performance.
4+
5+
## 📋 Prerequisites
6+
7+
To run the Stagehand API locally, ensure you have the following installed:
8+
9+
- Node.js
10+
- pnpm
11+
12+
## 🛠 Installation
13+
14+
1. Clone the repository:
15+
16+
```bash
17+
git clone https://github.com/browserbase/stagehand/
18+
cd stagehand/packages/server
19+
```
20+
21+
2. Install dependencies:
22+
23+
```bash
24+
pnpm install
25+
```
26+
27+
3. Set up environment variables:
28+
29+
```bash
30+
cp .env.example .env
31+
```
32+
33+
4. Configure your `.env` file with the environment variables required by `src/lib/env.ts` (BB environment, API base URLs, etc.).
34+
35+
5. `pnpm dev`
36+

‎packages/server/openapi.v3.yaml‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
openapi: 3.0.0
2+
info:
3+
title: Stagehand API
4+
description: Stagehand API Documentation
5+
version: 1.0.0
6+
components:
7+
schemas: {}
8+
paths:
9+
/v1/sessions/{id}/act:
10+
post:
11+
requestBody:
12+
content:
13+
application/json:
14+
schema:
15+
anyOf:
16+
- type: object
17+
properties:
18+
action:
19+
type: string
20+
minLength: 1
21+
useVision:
22+
anyOf:
23+
- type: string
24+
enum:
25+
- fallback
26+
- type: boolean
27+
variables:
28+
type: object
29+
additionalProperties:
30+
type: string
31+
domSettleTimeoutMs:
32+
type: number
33+
required:
34+
- action
35+
additionalProperties: false
36+
- type: object
37+
properties:
38+
selector:
39+
type: string
40+
description:
41+
type: string
42+
backendNodeId:
43+
type: number
44+
method:
45+
type: string
46+
arguments:
47+
type: array
48+
items:
49+
type: string
50+
required:
51+
- selector
52+
- description
53+
additionalProperties: false
54+
parameters:
55+
- schema:
56+
type: string
57+
in: path
58+
name: id
59+
required: true
60+
responses:
61+
"200":
62+
description: Default Response
63+
/v1/sessions/{id}/end:
64+
post:
65+
parameters:
66+
- schema:
67+
type: string
68+
in: path
69+
name: id
70+
required: true
71+
responses:
72+
"200":
73+
description: Default Response
74+
/v1/sessions/{id}/extract:
75+
post:
76+
requestBody:
77+
content:
78+
application/json:
79+
schema:
80+
type: object
81+
properties:
82+
instruction:
83+
type: string
84+
schemaDefinition:
85+
type: object
86+
additionalProperties: {}
87+
useTextExtract:
88+
type: boolean
89+
selector:
90+
type: string
91+
required:
92+
- instruction
93+
- schemaDefinition
94+
additionalProperties: false
95+
required: true
96+
parameters:
97+
- schema:
98+
type: string
99+
in: path
100+
name: id
101+
required: true
102+
responses:
103+
"200":
104+
description: Default Response
105+
/v1/healthcheck:
106+
get:
107+
responses:
108+
"200":
109+
description: Default Response
110+
content:
111+
application/json:
112+
schema:
113+
type: object
114+
properties:
115+
status:
116+
type: string
117+
timestamp:
118+
type: string
119+
/v1/sessions/{id}/navigate:
120+
post:
121+
requestBody:
122+
content:
123+
application/json:
124+
schema:
125+
type: object
126+
properties:
127+
url:
128+
type: string
129+
options:
130+
type: object
131+
properties:
132+
referer:
133+
type: string
134+
timeout:
135+
type: number
136+
waitUntil:
137+
type: string
138+
enum:
139+
- load
140+
- domcontentloaded
141+
- networkidle
142+
- commit
143+
additionalProperties: false
144+
required:
145+
- url
146+
additionalProperties: false
147+
required: true
148+
parameters:
149+
- schema:
150+
type: string
151+
in: path
152+
name: id
153+
required: true
154+
responses:
155+
"200":
156+
description: Default Response
157+
/v1/sessions/{id}/observe:
158+
post:
159+
requestBody:
160+
content:
161+
application/json:
162+
schema:
163+
type: object
164+
properties:
165+
instruction:
166+
type: string
167+
modelName:
168+
type: string
169+
modelClientOptions:
170+
type: object
171+
additionalProperties: true
172+
domSettleTimeoutMs:
173+
type: number
174+
returnAction:
175+
type: boolean
176+
onlyVisible:
177+
type: boolean
178+
drawOverlay:
179+
type: boolean
180+
additionalProperties: false
181+
parameters:
182+
- schema:
183+
type: string
184+
in: path
185+
name: id
186+
required: true
187+
responses:
188+
"200":
189+
description: Default Response
190+
/v1/sessions/start:
191+
post:
192+
requestBody:
193+
content:
194+
application/json:
195+
schema:
196+
type: object
197+
properties:
198+
modelName:
199+
type: string
200+
domSettleTimeoutMs:
201+
type: number
202+
verbose:
203+
type: string
204+
enum:
205+
- "0"
206+
- "1"
207+
- "2"
208+
debugDom:
209+
type: boolean
210+
systemPrompt:
211+
type: string
212+
browserbaseSessionCreateParams:
213+
type: object
214+
required:
215+
- modelName
216+
additionalProperties: false
217+
required: true
218+
responses:
219+
"200":
220+
description: Default Response
221+
/v1/sessions/{id}/screenshot:
222+
get:
223+
parameters:
224+
- schema:
225+
type: string
226+
in: path
227+
name: id
228+
required: true
229+
responses:
230+
"200":
231+
description: Default Response
232+
servers:
233+
- url: http://localhost:3000
234+
description: Development Server
235+
externalDocs:
236+
url: https://docs.stagehand.dev/
237+
description: Find more information here

‎packages/server/package.json‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
"name": "@browserbasehq/stagehand-server",
3+
"version": "3.0.5",
4+
"description": "Stagehand API server",
5+
"type": "module",
6+
"private": true,
7+
"scripts": {
8+
"build": "tsc && tsc-alias",
9+
"dev": "tsx watch src/server.ts",
10+
"lint": "cd ../.. && prettier --check packages/server && cd packages/server && eslint .",
11+
"typecheck": "tsc --noEmit"
12+
},
13+
"dependencies": {
14+
"@browserbasehq/sdk": "^2.4.0",
15+
"@browserbasehq/stagehand": "workspace:*",
16+
"@fastify/cors": "^11.0.1",
17+
"@t3-oss/env-core": "^0.13.8",
18+
"dotenv": "^16.4.5",
19+
"fastify": "^5.3.2",
20+
"fastify-metrics": "^12.1.0",
21+
"fastify-plugin": "^4.5.1",
22+
"http-status-codes": "^2.3.0",
23+
"pino": "^9.7.0",
24+
"pino-pretty": "^11.3.0",
25+
"playwright": "1.52.0",
26+
"uuid": "^11.0.5",
27+
"zod": "^3.25.76",
28+
"zod-to-json-schema": "^3.24.3"
29+
},
30+
"devDependencies": {
31+
"@types/node": "22.13.1",
32+
"eslint": "^9.7.0",
33+
"openai": "4.87.1",
34+
"tsc-alias": "^1.8.10",
35+
"tsx": "^4.18.0",
36+
"typescript": "~5.9.2"
37+
},
38+
"repository": {
39+
"type": "git",
40+
"url": "git+https://github.com/browserbase/stagehand.git",
41+
"directory": "packages/server"
42+
},
43+
"bugs": {
44+
"url": "https://github.com/browserbase/stagehand/issues"
45+
},
46+
"homepage": "https://stagehand.dev"
47+
}

0 commit comments

Comments
 (0)