Cursor Rules — Scrapybara Docs

.cursorrules

Python

TypeScript

.cursorrules

1 You are working with Scrapybara, a Python SDK for deploying and managing remote desktop instances for AI agents. Use this guide to properly interact with the SDK.
2 
3 CORE SDK USAGE:
4 
5 - Initialize client: from scrapybara import Scrapybara; client = Scrapybara(api_key="KEY")
6 - Instance lifecycle:
7     instance = client.start_ubuntu(timeout_hours=1)
8     instance.pause() # Pause to save resources
9     instance.resume(timeout_hours=1) # Resume work
10     instance.stop() # Terminate and clean up
11 - Instance types:
12     ubuntu_instance = client.start_ubuntu(): supports bash, computer, edit, browser
13     browser_instance = client.start_browser(): supports computer, browser
14     windows_instance = client.start_windows(): supports computer
15 
16 CORE INSTANCE OPERATIONS:
17 
18 - Screenshots: instance.screenshot().base_64_image
19 - Bash commands: instance.bash(command="ls -la")
20 - Mouse control: instance.computer(action="mouse_move", coordinate=[x, y])
21 - Click actions: instance.computer(action="left_click")
22 - File operations: instance.file.read(path="/path/file"), instance.file.write(path="/path/file", content="data")
23 
24 ACT SDK (Primary Focus):
25 
26 - Purpose: Enables building computer use agents with unified tools and model interfaces
27 - Core components:
28 
29 1. Model: Handles LLM integration (currently Anthropic)
30     from scrapybara.anthropic import Anthropic
31     model = Anthropic() # Or model = Anthropic(api_key="KEY") for own key
32 
33 2. Tools: Interface for computer interactions
34     - BashTool: Run shell commands
35     - ComputerTool: Mouse/keyboard control
36     - EditTool: File operations
37     tools = [
38         BashTool(instance),
39         ComputerTool(instance),
40         EditTool(instance),
41     ]
42 
43 3. Prompt:
44     - system: system prompt, recommend to use UBUNTU_SYSTEM_PROMPT, BROWSER_SYSTEM_PROMPT, WINDOWS_SYSTEM_PROMPT
45     - prompt: simple user prompt
46     - messages: list of messages
47     - Only include either prompt or messages, not both
48 
49 response = client.act(
50     model=Anthropic(),
51     tools=tools,
52     system=UBUNTU_SYSTEM_PROMPT,
53     prompt="Task",
54     on_step=handle_step
55 )
56 messages = response.messages
57 steps = response.steps
58 text = response.text
59 output = response.output
60 usage = response.usage
61 
62 MESSAGE HANDLING:
63 
64 - Response Structure: Messages are structured with roles (user/assistant/tool) and typed content
65 - Content Types:
66 - TextPart: Simple text content
67     TextPart(type="text", text="content")
68 - ImagePart: Base64 or URL images
69     ImagePart(type="image", image="base64...", mime_type="image/png")
70 - ToolCallPart: Tool invocations
71     ToolCallPart(
72         type="tool-call",
73         tool_call_id="id",
74         tool_name="bash",
75         args={"command": "ls"}
76     )
77 - ToolResultPart: Tool execution results
78     ToolResultPart(
79         type="tool-result",
80         tool_call_id="id",
81         tool_name="bash",
82         result="output",
83         is_error=False
84     )
85 
86 STEP HANDLING:
87 
88 # Access step information in callbacks
89 def handle_step(step: Step):
90     print(f"Text: {step.text}")
91     if step.tool_calls:
92         for call in step.tool_calls:
93             print(f"Tool: {call.tool_name}")
94     if step.tool_results:
95         for result in step.tool_results:
96             print(f"Result: {result.result}")
97     print(f"Tokens: {step.usage.total_tokens if step.usage else 'N/A'}")
98 
99 STRUCTURED OUTPUT:
100 Use the schema parameter to define a desired structured output. The response's output field will contain the validated typed data returned by the model.
101 
102 class HNSchema(BaseModel):
103     class Post(BaseModel):
104         title: str
105         url: str 
106         points: int
107     posts: List[Post]
108 
109 response = client.act(
110     model=Anthropic(),
111     tools=tools,
112     schema=HNSchema,
113     system=SYSTEM_PROMPT,
114     prompt="Get the top 10 posts on Hacker News",
115 )
116 posts = response.output.posts
117 
118 TOKEN USAGE:
119 
120 - Track token usage through TokenUsage objects
121 - Fields: prompt_tokens, completion_tokens, total_tokens
122 - Available in both Step and ActResponse objects
123 
124 Here's a brief example of how to use the Scrapybara SDK:
125 
126 from scrapybara import Scrapybara
127 from scrapybara.anthropic import Anthropic
128 from scrapybara.prompts import UBUNTU_SYSTEM_PROMPT
129 from scrapybara.tools import BashTool, ComputerTool, EditTool
130 
131 client = Scrapybara()
132 instance = client.start_ubuntu()
133 instance.browser.start()
134 
135 response = client.act(
136     model=Anthropic(),
137     tools=[
138         BashTool(instance),
139         ComputerTool(instance),
140         EditTool(instance),
141     ],
142     system=UBUNTU_SYSTEM_PROMPT,
143     prompt="Go to the YC website and fetch the HTML",
144     on_step=lambda step: print(f"{step}\n"),
145 )
146 messages = response.messages
147 steps = response.steps
148 text = response.text
149 output = response.output
150 usage = response.usage
151 
152 instance.browser.stop()
153 instance.stop()
154 
155 EXECUTION PATTERNS:
156 
157 1. Basic agent execution:
158 
159 response = client.act(
160     model=Anthropic(),
161     tools=tools,
162     system="System context here",
163     prompt="Task description"
164 )
165 
166 2. Browser automation:
167 
168 cdp_url = instance.browser.start().cdp_url
169 auth_state_id = instance.browser.save_auth(name="default").auth_state_id  # Save auth
170 instance.browser.authenticate(auth_state_id=auth_state_id)  # Reuse auth
171 
172 3. File management:
173 
174 instance.file.write("/tmp/data.txt", "content")
175 content = instance.file.read("/tmp/data.txt").content
176 
177 
178 IMPORTANT GUIDELINES:
179 
180 - Always stop instances after use to prevent unnecessary billing
181 - Use async client (AsyncScrapybara) for non-blocking operations
182 - Handle API errors with try/except ApiError blocks
183 - Default timeout is 60s; customize with timeout parameter or request_options
184 - Instance auto-terminates after 1 hour by default
185 - For browser operations, always start browser before BrowserTool usage
186 - Prefer bash commands over GUI interactions for launching applications
187 
188 ERROR HANDLING:
189 
190 from scrapybara.core.api_error import ApiError
191 try:
192     client.start_ubuntu()
193 except ApiError as e:
194     print(f"Error {e.status_code}: {e.body}")
195 
196 BROWSER TOOL OPERATIONS:
197 
198 - Required setup:
199 cdp_url = instance.browser.start().cdp_url
200 tools = [BrowserTool(instance)]
201 - Commands: go_to, get_html, evaluate, click, type, screenshot, get_text, get_attribute
202 - Always handle browser authentication states appropriately
203 
204 ENV VARIABLES & CONFIGURATION:
205 
206 - Set env vars: instance.env.set({"API_KEY": "value"})
207 - Get env vars: vars = instance.env.get().variables
208 - Delete env vars: instance.env.delete(["VAR_NAME"])
209 
210 Remember to handle resources properly and implement appropriate error handling in your code. This SDK is primarily designed for AI agent automation tasks, so structure your code accordingly.

llms-full.txt

Need more context? Check out llms-full.txt.

1	You are working with Scrapybara, a Python SDK for deploying and managing remote desktop instances for AI agents. Use this guide to properly interact with the SDK.
2
3	CORE SDK USAGE:
4
5	- Initialize client: from scrapybara import Scrapybara; client = Scrapybara(api_key="KEY")
6	- Instance lifecycle:
7	instance = client.start_ubuntu(timeout_hours=1)
8	instance.pause() # Pause to save resources
9	instance.resume(timeout_hours=1) # Resume work
10	instance.stop() # Terminate and clean up
11	- Instance types:
12	ubuntu_instance = client.start_ubuntu(): supports bash, computer, edit, browser
13	browser_instance = client.start_browser(): supports computer, browser
14	windows_instance = client.start_windows(): supports computer
15
16	CORE INSTANCE OPERATIONS:
17
18	- Screenshots: instance.screenshot().base_64_image
19	- Bash commands: instance.bash(command="ls -la")
20	- Mouse control: instance.computer(action="mouse_move", coordinate=[x, y])
21	- Click actions: instance.computer(action="left_click")
22	- File operations: instance.file.read(path="/path/file"), instance.file.write(path="/path/file", content="data")
23
24	ACT SDK (Primary Focus):
25
26	- Purpose: Enables building computer use agents with unified tools and model interfaces
27	- Core components:
28
29	1. Model: Handles LLM integration (currently Anthropic)
30	from scrapybara.anthropic import Anthropic
31	model = Anthropic() # Or model = Anthropic(api_key="KEY") for own key
32
33	2. Tools: Interface for computer interactions
34	- BashTool: Run shell commands
35	- ComputerTool: Mouse/keyboard control
36	- EditTool: File operations
37	tools = [
38	BashTool(instance),
39	ComputerTool(instance),
40	EditTool(instance),
41	]
42
43	3. Prompt:
44	- system: system prompt, recommend to use UBUNTU_SYSTEM_PROMPT, BROWSER_SYSTEM_PROMPT, WINDOWS_SYSTEM_PROMPT
45	- prompt: simple user prompt
46	- messages: list of messages
47	- Only include either prompt or messages, not both
48
49	response = client.act(
50	model=Anthropic(),
51	tools=tools,
52	system=UBUNTU_SYSTEM_PROMPT,
53	prompt="Task",
54	on_step=handle_step
55	)
56	messages = response.messages
57	steps = response.steps
58	text = response.text
59	output = response.output
60	usage = response.usage
61
62	MESSAGE HANDLING:
63
64	- Response Structure: Messages are structured with roles (user/assistant/tool) and typed content
65	- Content Types:
66	- TextPart: Simple text content
67	TextPart(type="text", text="content")
68	- ImagePart: Base64 or URL images
69	ImagePart(type="image", image="base64...", mime_type="image/png")
70	- ToolCallPart: Tool invocations
71	ToolCallPart(
72	type="tool-call",
73	tool_call_id="id",
74	tool_name="bash",
75	args={"command": "ls"}
76	)
77	- ToolResultPart: Tool execution results
78	ToolResultPart(
79	type="tool-result",
80	tool_call_id="id",
81	tool_name="bash",
82	result="output",
83	is_error=False
84	)
85
86	STEP HANDLING:
87
88	# Access step information in callbacks
89	def handle_step(step: Step):
90	print(f"Text: {step.text}")
91	if step.tool_calls:
92	for call in step.tool_calls:
93	print(f"Tool: {call.tool_name}")
94	if step.tool_results:
95	for result in step.tool_results:
96	print(f"Result: {result.result}")
97	print(f"Tokens: {step.usage.total_tokens if step.usage else 'N/A'}")
98
99	STRUCTURED OUTPUT:
100	Use the schema parameter to define a desired structured output. The response's output field will contain the validated typed data returned by the model.
101
102	class HNSchema(BaseModel):
103	class Post(BaseModel):
104	title: str
105	url: str
106	points: int
107	posts: List[Post]
108
109	response = client.act(
110	model=Anthropic(),
111	tools=tools,
112	schema=HNSchema,
113	system=SYSTEM_PROMPT,
114	prompt="Get the top 10 posts on Hacker News",
115	)
116	posts = response.output.posts
117
118	TOKEN USAGE:
119
120	- Track token usage through TokenUsage objects
121	- Fields: prompt_tokens, completion_tokens, total_tokens
122	- Available in both Step and ActResponse objects
123
124	Here's a brief example of how to use the Scrapybara SDK:
125
126	from scrapybara import Scrapybara
127	from scrapybara.anthropic import Anthropic
128	from scrapybara.prompts import UBUNTU_SYSTEM_PROMPT
129	from scrapybara.tools import BashTool, ComputerTool, EditTool
130
131	client = Scrapybara()
132	instance = client.start_ubuntu()
133	instance.browser.start()
134
135	response = client.act(
136	model=Anthropic(),
137	tools=[
138	BashTool(instance),
139	ComputerTool(instance),
140	EditTool(instance),
141	],
142	system=UBUNTU_SYSTEM_PROMPT,
143	prompt="Go to the YC website and fetch the HTML",
144	on_step=lambda step: print(f"{step}\n"),
145	)
146	messages = response.messages
147	steps = response.steps
148	text = response.text
149	output = response.output
150	usage = response.usage
151
152	instance.browser.stop()
153	instance.stop()
154
155	EXECUTION PATTERNS:
156
157	1. Basic agent execution:
158
159	response = client.act(
160	model=Anthropic(),
161	tools=tools,
162	system="System context here",
163	prompt="Task description"
164	)
165
166	2. Browser automation:
167
168	cdp_url = instance.browser.start().cdp_url
169	auth_state_id = instance.browser.save_auth(name="default").auth_state_id # Save auth
170	instance.browser.authenticate(auth_state_id=auth_state_id) # Reuse auth
171
172	3. File management:
173
174	instance.file.write("/tmp/data.txt", "content")
175	content = instance.file.read("/tmp/data.txt").content
176
177
178	IMPORTANT GUIDELINES:
179
180	- Always stop instances after use to prevent unnecessary billing
181	- Use async client (AsyncScrapybara) for non-blocking operations
182	- Handle API errors with try/except ApiError blocks
183	- Default timeout is 60s; customize with timeout parameter or request_options
184	- Instance auto-terminates after 1 hour by default
185	- For browser operations, always start browser before BrowserTool usage
186	- Prefer bash commands over GUI interactions for launching applications
187
188	ERROR HANDLING:
189
190	from scrapybara.core.api_error import ApiError
191	try:
192	client.start_ubuntu()
193	except ApiError as e:
194	print(f"Error {e.status_code}: {e.body}")
195
196	BROWSER TOOL OPERATIONS:
197
198	- Required setup:
199	cdp_url = instance.browser.start().cdp_url
200	tools = [BrowserTool(instance)]
201	- Commands: go_to, get_html, evaluate, click, type, screenshot, get_text, get_attribute
202	- Always handle browser authentication states appropriately
203
204	ENV VARIABLES & CONFIGURATION:
205
206	- Set env vars: instance.env.set({"API_KEY": "value"})
207	- Get env vars: vars = instance.env.get().variables
208	- Delete env vars: instance.env.delete(["VAR_NAME"])
209
210	Remember to handle resources properly and implement appropriate error handling in your code. This SDK is primarily designed for AI agent automation tasks, so structure your code accordingly.