> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.scrapybara.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.scrapybara.com/_mcp/server.

# Best Practices

## Manage instance usage

Instances are billed per usage. When launching an instance, you can specify its timeout before it is automatically terminated (default is 1 hour).

#### Python

```python
instance = client.start_ubuntu(timeout=3) # 3 hours
```

#### TypeScript

```typescript
const instance = await client.startUbuntu({ timeout: 3 }); // 3 hours
```

To save costs, pause the instance to resume it later, or stop the instance once you no longer need to control the desktop environment and access its stored data.

#### Python

```python Pause/resume
instance.pause()
instance.resume()
```

```python Stop
instance.stop()
```

#### TypeScript

```typescript Pause/resume
await instance.pause();
await instance.resume();
```

```typescript Stop
await instance.stop();
```

## Take actions programmatically

When possible, take actions programmatically rather than relying on the agent to do so. For example, using `instance.bash` provides a faster way to launch apps compared to having the model use mouse/keyboard interactions. If you know the agent's workflow will happen on a specific application, you can launch it before prompting the agent to take actions. The same applies for browser automation: it is often easier to manipulate the browser programmatically with `instance.browser` and Playwright than relying on the agent itself.

## Initialize the browser

For agents requiring programmatic browser interaction, initialize and configure the browser immediately after instance creation. This ensures the browser environment is ready before any browser tool calls are made.

#### Python

```python
instance = client.start_ubuntu()
instance.browser.start()
instance.browser.authenticate(auth_state_id="auth_state_id")
```

#### TypeScript

```typescript
const instance = await client.startUbuntu();
await instance.browser.start();
await instance.browser.authenticate(auth_state_id="auth_state_id");
```

## Optimize your prompt

Each model (OpenAI and Anthropic) has its own specialized system prompt optimized for computer use tasks. We recommend using these model-specific prompts for best results.

#### Python

```python OpenAI
from scrapybara.openai import OpenAI, UBUNTU_SYSTEM_PROMPT as OPENAI_UBUNTU_PROMPT

client.act(
    model=OpenAI(),
    system=OPENAI_UBUNTU_PROMPT,
    # ...
)
```

```python Anthropic
from scrapybara.anthropic import Anthropic, UBUNTU_SYSTEM_PROMPT as ANTHROPIC_UBUNTU_PROMPT

client.act(
    model=Anthropic(),
    system=ANTHROPIC_UBUNTU_PROMPT,
    # ...
)
```

#### TypeScript

```typescript OpenAI
import { openai, UBUNTU_SYSTEM_PROMPT as OPENAI_UBUNTU_PROMPT } from "scrapybara/openai";

await client.act({
  model: openai(),
  system: OPENAI_UBUNTU_PROMPT,
  // ...
});
```

```typescript Anthropic
import { anthropic, UBUNTU_SYSTEM_PROMPT as ANTHROPIC_UBUNTU_PROMPT } from "scrapybara/anthropic";

await client.act({
  model: anthropic(),
  system: ANTHROPIC_UBUNTU_PROMPT,
  // ...
});
```

For more complex tasks, you can extend the model-specific system prompt by defining additional task requirements:

#### Python

```python
# Use the appropriate system prompt for your chosen model
system = f"""{UBUNTU_SYSTEM_PROMPT}

<TASK>
{task}
</TASK>"""
```

#### TypeScript

```typescript
// Use the appropriate system prompt for your chosen model
const system = `${UBUNTU_SYSTEM_PROMPT}

<TASK>
${task}
</TASK>`;
```

Here are some tips from [Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/computer-use) to improve the agent's performance:

1. Specify simple, well-defined tasks and provide explicit instructions for each step.
2. Models sometimes assume outcomes of their actions without explicitly checking their results. To prevent this you can prompt the model with `After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.`
3. Some UI elements (like dropdowns and scrollbars) might be tricky for models to manipulate using mouse movements. If you experience this, try prompting the model to use keyboard shortcuts.
4. For repeatable tasks or UI interactions, include example screenshots and tool calls of successful outcomes in your prompt.
5. If you need the model to log in, provide it with the username and password in your prompt inside xml tags like `<robot_credentials>`. Using computer use within applications that require login increases the risk of bad outcomes as a result of prompt injection.