> 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.

# Quickstart

## Deploy your first instance

#### Python

#### Generate API key

Sign up on our [dashboard](https://scrapybara.com/dashboard). An API key will be generated for you automatically.

#### Install SDK

Install the Python SDK with pip.

```bash
pip install scrapybara
```

#### Configure client

Configure the client with your API key.

```python
from scrapybara import Scrapybara

client = Scrapybara(api_key="your_api_key")
```

#### Start an instance

Start an instance with your desired configuration. You can choose from Ubuntu, Browser, and Windows instances. We recommend using Ubuntu for most tasks.

```python
instance = client.start_ubuntu(
    timeout_hours=1,
)

# browser_instance = client.start_browser(
#     timeout_hours=1,
# )
```

#### Get the stream URL

Get the stream URL to view and interact with the instance manually.

```python
stream_url = instance.get_stream_url().stream_url
```

#### Interact with the instance

Interact with the instance with `computer` and `bash`.

**`Move the mouse`**

```python Move the mouse
instance.computer(
    action="move_mouse",
    coordinates=[200, 100]
)
```

**`Left click`**

```python Left click
instance.computer(
    action="click_mouse",
    button="left"
)
```

**`Type hello`**

```python Type hello
instance.computer(
    action="type_text",
    text="Hello, world!"
)
```

**`Run a bash command`**

```python Run a bash command
result = instance.bash(
    command="ls -la"
)
```

#### Connect to the browser

Connect to the browser with Playwright to enable programmatic browser control and authenticated browser sessions. Learn more [here](/browser).

**`Connect to Playwright`**

```python Connect to Playwright
from playwright.sync_api import sync_playwright

cdp_url = instance.browser.start().cdp_url
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(cdp_url)
```

**`Save the auth state`**

```python Save the auth state
auth_state_id = instance.browser.save_auth(name="default").auth_state_id
```

**`Reuse the auth state on other instances`**

```python Reuse the auth state on other instances
instance.browser.authenticate(auth_state_id=auth_state_id)
```

#### Take action!

Build your first agent with the Act SDK to control your Scrapybara instance with `BashTool`, `ComputerTool`, `EditTool`. Learn more [here](/act-sdk).

```python
from scrapybara.tools import BashTool, ComputerTool, EditTool
from scrapybara.openai import OpenAI, UBUNTU_SYSTEM_PROMPT

response = client.act(
    model=OpenAI(),
    tools=[
        BashTool(instance),
        ComputerTool(instance),
        EditTool(instance),
    ],
    system=UBUNTU_SYSTEM_PROMPT,
    prompt="Go to the top link on Hacker News",
    on_step=lambda step: print(step.text),
)
```

#### Stop the instance

Stop the instance when you're done. This will delete all data stored during the session.

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

#### TypeScript

#### Generate API key

Sign up on our [dashboard](https://scrapybara.com/dashboard). An API key will be generated for you automatically.

#### Install SDK

Install the TypeScript SDK with npm, yarn, or pnpm.

```bash
npm install scrapybara
yarn add scrapybara
pnpm add scrapybara
```

#### Configure client

Configure the client with your API key.

```typescript
import { ScrapybaraClient } from "scrapybara";

const client = new ScrapybaraClient({ apiKey: "your_api_key" });
```

#### Start an instance

Start an instance with your desired configuration. You can choose from Ubuntu, Browser, and Windows instances. We recommend using Ubuntu for most tasks.

```typescript
const instance = await client.startUbuntu({
    timeoutHours: 1,
});

// const browserInstance = await client.startBrowser({
//     timeoutHours: 1,
// });
```

#### Get the stream URL

Get the stream URL to view and interact with the instance manually.

```typescript
const streamUrl = await instance.getStreamUrl().streamUrl;
```

#### Interact with the instance

Interact with the instance with `computer` and `bash`.

**`Move the mouse`**

```typescript Move the mouse
await instance.computer({
    action: "move_mouse",
    coordinates: [200, 100]
});
```

**`Left click`**

```typescript Left click
await instance.computer({
    action: "click_mouse",
    button: "left"
});
```

**`Type hello`**

```typescript Type hello
await instance.computer({
    action: "type_text",
    text: "Hello, world!"
});
```

**`Run a bash command`**

```typescript Run a bash command
const result = await instance.bash({
    command: "ls -la"
});
```

#### Connect to the browser

Connect to the browser with Playwright to enable programmatic browser control and authenticated browser sessions. Learn more [here](/browser).

**`Connect to Playwright`**

```typescript Connect to Playwright
import { chromium } from "playwright";

const cdpUrl = await instance.browser.start().cdpUrl;
const browser = await chromium.connectOverCDP(cdpUrl);
```

**`Save the auth state`**

```typescript Save the auth state
const authStateId = await instance.browser.saveAuth({ name: "default" }).authStateId;
```

**`Reuse the auth state on other instances`**

```typescript Reuse the auth state on other instances
await instance.browser.authenticate({ authStateId });
```

#### Take action!

Build your first agent with the Act SDK to control your Scrapybara instance with `BashTool`, `ComputerTool`, `EditTool`. Learn more [here](/act-sdk).

```typescript
import { bashTool, computerTool, editTool } from "scrapybara/tools";
import { openai, UBUNTU_SYSTEM_PROMPT } from "scrapybara/openai";

const { messages, steps, text, usage } = await client.act({
  tools: [
    bashTool(instance),
    computerTool(instance),
    editTool(instance),
  ],
  model: openai(),
  system: UBUNTU_SYSTEM_PROMPT,
  prompt: "Go to the top link on Hacker News",
  onStep: (step) => console.log(step.text),
});
```

#### Stop the instance

Stop the instance when you're done. This will delete all data stored during the session.

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

## Start building

Be sure to check out our other resources to learn more. Happy building! ₍ᐢ•(ܫ)•ᐢ₎

#### [Act SDK](/act-sdk)

Take action with computer use agents

#### [API Reference](/api-reference)

Check out our API reference docs

#### [Ubuntu](/ubuntu)

Learn about the UbuntuInstance

#### [Browser](/browser)

Learn about the BrowserInstance