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

# Ubuntu

## UbuntuInstance

The `UbuntuInstance` is a Ubuntu 22.04 desktop that supports interactive streaming, computer actions, bash commands, filesystem management, built-in Jupyter notebooks, and Chromium browser support. We recommend using this instance type for most tasks.

* Fast start up time
* 1x compute cost

## Start an Ubuntu instance

#### Python

`python instance = client.start_ubuntu() `

#### TypeScript

`typescript const instance = await client.startUbuntu(); `

## Available actions

### screenshot

Take a base64 encoded image of the current desktop

#### Python

`python base_64_image = instance.screenshot().base_64_image `

#### TypeScript

`typescript const base64Image = await instance.screenshot(); `

### get\_stream\_url

Get the interactive stream URL

#### Python

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

#### TypeScript

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

### computer

Perform computer actions with the mouse and keyboard

#### `move_mouse`

Move mouse cursor to specific coordinates

**`coordinates`** `array` — required

\[x, y] coordinates to move to

---

**`hold_keys`** `array`

List of modifier keys to hold during the action

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Move mouse`**

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

**`Move mouse while holding shift`**

```python Move mouse while holding shift
instance.computer(action="move_mouse", coordinates=[100, 200], hold_keys=["shift"])
```

**`Move mouse without taking a screenshot`**

```python Move mouse without taking a screenshot
instance.computer(action="move_mouse", coordinates=[100, 200], screenshot=False)
```

#### TypeScript

**`Move mouse`**

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

**`Move mouse while holding shift`**

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

**`Move mouse without taking a screenshot`**

```typescript Move mouse without taking a screenshot
await instance.computer({action: "move_mouse", coordinates: [100, 200], screenshot: false});
```

#### `click_mouse`

Perform a mouse click at current position or specified coordinates

**`button`** `string` — required

Mouse button to click ("left", "right", "middle", "back", "forward")

---

**`click_type`** `string` — default: click

Type of click action ("down", "up", "click")

---

**`coordinates`** `array`

\[x, y] coordinates to click at

---

**`num_clicks`** `number` — default: 1

Number of clicks

---

**`hold_keys`** `array`

List of modifier keys to hold during the action

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Left click at current position`**

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

**`Right click at coordinates`**

```python Right click at coordinates
instance.computer(action="click_mouse", button="right", coordinates=[300, 400])
```

**`Mouse down`**

```python Mouse down
instance.computer(action="click_mouse", button="left", click_type="down")
```

**`Double click at coordinates`**

```python Double click at coordinates
instance.computer(action="click_mouse", button="left", num_clicks=2, coordinates=[500, 300])
```

#### TypeScript

**`Left click at current position`**

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

**`Right click at coordinates`**

```typescript Right click at coordinates
await instance.computer({action: "click_mouse", button: "right", coordinates: [300, 400]});
```

**`Mouse down`**

```typescript Mouse down
await instance.computer({action: "click_mouse", button: "left", clickType: "down"});
```

**`Double click at coordinates`**

```typescript Double click at coordinates
await instance.computer({action: "click_mouse", button: "left", numClicks: 2, coordinates: [500, 300]});
```

#### `drag_mouse`

Click and drag from current position to specified coordinates

**`path`** `array` — required

List of \[x, y] coordinate pairs defining the drag path

---

**`hold_keys`** `array`

List of modifier keys to hold during the action

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Drag to coordinates`**

```python Drag to coordinates
instance.computer(action="drag_mouse", path=[[100, 200], [300, 400]])
```

#### TypeScript

**`Drag to coordinates`**

```typescript Drag to coordinates
await instance.computer({action: "drag_mouse", path: [[100, 200], [300, 400]]});
```

#### `scroll`

Scroll horizontally and/or vertically

**`coordinates`** `array`

\[x, y] coordinates to scroll at

---

**`delta_x`** `number` — default: 0

Horizontal scroll amount

---

**`delta_y`** `number` — default: 0

Vertical scroll amount

---

**`hold_keys`** `array`

List of modifier keys to hold during the action

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Scroll down`**

```python Scroll down
instance.computer(action="scroll", coordinates=[100, 100], delta_x=0, delta_y=200)
```

**`Scroll right`**

```python Scroll right
instance.computer(action="scroll", coordinates=[100, 100], delta_x=200, delta_y=0)
```

#### TypeScript

**`Scroll down`**

```typescript Scroll down
await instance.computer({action: "scroll", coordinates: [100, 100], deltaX: 0, deltaY: 200});
```

**`Scroll right`**

```typescript Scroll right
await instance.computer({action: "scroll", coordinates: [100, 100], deltaX: 100, deltaY: 0});
```

#### `press_key`

Press a key or combination of keys. Scrapybara supports keys defined by [X keysyms](https://github.com/D-Programming-Deimos/libX11/blob/master/c/X11/keysymdef.h). Common aliases are also supported:

* `alt` → `Alt_L`
* `ctrl`, `control` → `Control_L`
* `meta` → `Meta_L`
* `super` → `Super_L`
* `shift` → `Shift_L`

**`keys`** `array` — required

List of keys to press

---

**`duration`** `number`

Time to hold keys in seconds

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Press ctrl+c`**

```python Press ctrl+c
instance.computer(action="press_key", keys=["ctrl", "c"])
```

**`Hold shift for 2 seconds`**

```python Hold shift for 2 seconds
instance.computer(action="press_key", keys=["shift"], duration=2)
```

**`Press enter/return`**

```python Press enter/return
instance.computer(action="press_key", keys=["Return"])
```

#### TypeScript

**`Press ctrl+c`**

```typescript Press ctrl+c
await instance.computer({action: "press_key", keys: ["ctrl", "c"]});
```

**`Hold shift for 2 seconds`**

```typescript Hold shift for 2 seconds
await instance.computer({action: "press_key", keys: ["shift"], duration: 2});
```

**`Press enter/return`**

```typescript Press enter/return
await instance.computer({action: "press_key", keys: ["Return"]});
```

#### `type_text`

Type text into the active window

**`text`** `string` — required

Text to type

---

**`hold_keys`** `array`

List of modifier keys to hold while typing

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Type text`**

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

**`Type text without taking a screenshot`**

```python Type text without taking a screenshot
instance.computer(action="type_text", text="Hello world", screenshot=False)
```

#### TypeScript

**`Type text`**

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

**`Type text without taking a screenshot`**

```typescript Type text without taking a screenshot
await instance.computer({action: "type_text", text: "Hello world", screenshot: false});
```

#### `wait`

Wait for a specified duration

**`duration`** `number` — required

Time to wait in seconds

---

**`screenshot`** `boolean` — default: true

Whether to take a screenshot after the action

---

#### Python

**`Wait for 3 seconds`**

```python Wait for 3 seconds
instance.computer(action="wait", duration=3)
```

#### TypeScript

**`Wait for 3 seconds`**

```typescript Wait for 3 seconds
await instance.computer({action: "wait", duration: 3});
```

#### `take_screenshot`

Take a screenshot of the desktop

#### Python

```python
screenshot = instance.computer(action="take_screenshot").base_64_image
```

#### TypeScript

```typescript
const screenshot = await instance.computer({action: "take_screenshot"}).base64Image;
```

#### `get_cursor_position`

Get current mouse cursor coordinates

#### Python

```python
cursor_position = instance.computer(action="get_cursor_position").output
```

#### TypeScript

```typescript
const cursorPosition = await instance.computer({action: "get_cursor_position"}).output;
```

### bash

Run a bash command

> **Note:** Bash commands time out after 10 seconds by default, but you can customize this with the `timeout` parameter. When a command times out, it will continue running in the session. To run other commands while waiting for a long-running command to complete, start them in a different session. Use `check_session` to check back on a session's status. Once a command finishes execution, the session becomes available again for new commands.

#### Python

**`Run a bash command`**

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

**`Run a command in a specific session`**

```python Run a command in a specific session
output = instance.bash(command="ls -la", session=1)
```

**`Run a command with custom timeout`**

```python Run a command with custom timeout
output = instance.bash(command="sleep 30", timeout=60)
```

**`Restart a session`**

```python Restart a session
instance.bash(restart=True, session=1)
```

**`List available bash sessions`**

```python List available bash sessions
sessions = instance.bash(list_sessions=True)
```

**`Check the status of a session`**

```python Check the status of a session
session_exists = instance.bash(check_session=1)
```

#### TypeScript

**`Run a bash command`**

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

**`Run a command in a specific session`**

```typescript Run a command in a specific session
const output = await instance.bash({command: "ls -la", session: 1});
```

**`Run a command with custom timeout`**

```typescript Run a command with custom timeout
const output = await instance.bash({command: "sleep 30", timeout: 60});
```

**`Restart a session`**

```typescript Restart a session
await instance.bash({restart: true, session: 1});
```

**`List available bash sessions`**

```typescript List available bash sessions
const sessions = await instance.bash({listSessions: true});
```

**`Check the status of a session`**

```typescript Check the status of a session
const sessionExists = await instance.bash({checkSession: 1});
```

### edit

> **Deprecated:** Please use the `file` tool instead which provides more comprehensive file management capabilities.

Edit a file on the instance

#### Python

**`Create a new file`**

```python Create a new file
instance.edit(command="create", path="hello.txt", file_text="Hello world")
```

**`Replace text in a file`**

```python Replace text in a file
instance.edit(command="str_replace", path="hello.txt", old_str="Hello", new_str="Hi")
```

**`Insert text at a specific line`**

```python Insert text at a specific line
instance.edit(command="insert", path="hello.txt", insert_line=2, file_text="New line")
```

#### TypeScript

**`Create a new file`**

```typescript Create a new file
await instance.edit({command: "create", path: "hello.txt", fileText: "Hello world"});
```

**`Replace text in a file`**

```typescript Replace text in a file
await instance.edit({command: "str_replace", path: "hello.txt", oldStr: "Hello", newStr: "Hi"});
```

**`Insert text at a specific line`**

```typescript Insert text at a specific line
await instance.edit({command: "insert", path: "hello.txt", insertLine: 2, fileText: "New line"});
```

### file

Manage files and directories on the instance

#### `read`

Read the content of a file in text or binary mode

**`path`** `string` — required

Path to the file to read

---

**`mode`** `string` — default: text

Read mode: "text" or "binary"

---

**`encoding`** `string` — default: utf-8

Text encoding when mode is "text"

---

#### Python

**`Read text file`**

```python Read text file
content = instance.file(command="read", path="my_file.txt")
```

**`Read binary file`**

```python Read binary file
binary_content = instance.file(command="read", path="image.png", mode="binary")
```

#### TypeScript

**`Read text file`**

```typescript Read text file
const content = await instance.file({command: "read", path: "my_file.txt"});
```

**`Read binary file`**

```typescript Read binary file
const binaryContent = await instance.file({command: "read", path: "image.png", mode: "binary"});
```

#### `write`

Write content to a file, overwriting if it exists

**`path`** `string` — required

Path to the file to write

---

**`content`** `string` — required

Content to write to the file

---

**`mode`** `string` — default: text

Write mode: "text" or "binary" (base64 encoded for binary)

---

**`encoding`** `string` — default: utf-8

Text encoding when mode is "text"

---

#### Python

**`Write text to file`**

```python Write text to file
instance.file(command="write", path="my_file.txt", content="Hello world")
```

#### TypeScript

**`Write text to file`**

```typescript Write text to file
await instance.file({command: "write", path: "my_file.txt", content: "Hello world"});
```

#### `append`

Append content to an existing file or create it if it doesn't exist

**`path`** `string` — required

Path to the file to append to

---

**`content`** `string` — required

Content to append to the file

---

**`mode`** `string` — default: text

Append mode: "text" or "binary" (base64 encoded for binary)

---

**`encoding`** `string` — default: utf-8

Text encoding when mode is "text"

---

#### Python

**`Append text`**

```python Append text
instance.file(command="append", path="my_file.txt", content="New content")
```

#### TypeScript

**`Append text`**

```typescript Append text
await instance.file({command: "append", path: "my_file.txt", content: "New content"});
```

#### `exists`

Check if a path exists

**`path`** `string` — required

Path to check

---

#### Python

**`Check if file exists`**

```python Check if file exists
exists = instance.file(command="exists", path="my_file.txt")
```

#### TypeScript

**`Check if file exists`**

```typescript Check if file exists
const exists = await instance.file({command: "exists", path: "my_file.txt"});
```

#### `list`

List the contents of a directory

**`path`** `string` — required

Path to the directory to list

---

#### Python

**`List directory contents`**

```python List directory contents
files = instance.file(command="list", path="my_directory")
```

#### TypeScript

**`List directory contents`**

```typescript List directory contents
const files = await instance.file({command: "list", path: "my_directory"});
```

#### `mkdir`

Create a directory, including parent directories if needed

**`path`** `string` — required

Path to the directory to create

---

#### Python

**`Create directory`**

```python Create directory
instance.file(command="mkdir", path="new_directory")
```

#### TypeScript

**`Create directory`**

```typescript Create directory
await instance.file({command: "mkdir", path: "new_directory"});
```

#### `rmdir`

Remove an empty directory

**`path`** `string` — required

Path to the directory to remove

---

#### Python

**`Remove directory`**

```python Remove directory
instance.file(command="rmdir", path="empty_directory")
```

#### TypeScript

**`Remove directory`**

```typescript Remove directory
await instance.file({command: "rmdir", path: "empty_directory"});
```

#### `delete`

Delete a file or directory

**`path`** `string` — required

Path to delete

---

**`recursive`** `boolean` — default: false

Delete directory contents recursively

---

#### Python

**`Delete file`**

```python Delete file
instance.file(command="delete", path="file.txt")
```

**`Delete directory recursively`**

```python Delete directory recursively
instance.file(command="delete", path="directory", recursive=True)
```

#### TypeScript

**`Delete file`**

```typescript Delete file
await instance.file({command: "delete", path: "file.txt"});
```

**`Delete directory recursively`**

```typescript Delete directory recursively
await instance.file({command: "delete", path: "directory", recursive: true});
```

#### `move`

Move or rename a file or directory

**`src`** `string` — required

Source path

---

**`dst`** `string` — required

Destination path

---

#### Python

**`Move or rename`**

```python Move or rename
instance.file(command="move", src="old_name.txt", dst="new_name.txt")
```

#### TypeScript

**`Move or rename`**

```typescript Move or rename
await instance.file({command: "move", src: "old_name.txt", dst: "new_name.txt"});
```

#### `copy`

Copy a file or directory

**`src`** `string` — required

Source path

---

**`dst`** `string` — required

Destination path

---

#### Python

**`Copy file or directory`**

```python Copy file or directory
instance.file(command="copy", src="source.txt", dst="destination.txt")
```

#### TypeScript

**`Copy file or directory`**

```typescript Copy file or directory
await instance.file({command: "copy", src: "source.txt", dst: "destination.txt"});
```

#### `view`

View file content with line numbers or list directory contents

**`path`** `string` — required

Path to view

---

**`view_range`** `array`

Optional \[start, end] line range to view

---

#### Python

**`View with line numbers`**

```python View with line numbers
content = instance.file(command="view", path="my_file.txt")
```

**`View specific line range`**

```python View specific line range
content = instance.file(command="view", path="my_file.txt", view_range=[10, 20])
```

#### TypeScript

**`View with line numbers`**

```typescript View with line numbers
const content = await instance.file({command: "view", path: "my_file.txt"});
```

**`View specific line range`**

```typescript View specific line range
const content = await instance.file({command: "view", path: "my_file.txt", viewRange: [10, 20]});
```

#### `create`

Create a new file with the given content, failing if it already exists

**`path`** `string` — required

Path to the file to create

---

**`content`** `string` — required

Content to write to the new file

---

**`mode`** `string` — default: text

Create mode: "text" or "binary" (base64 encoded for binary)

---

**`encoding`** `string` — default: utf-8

Text encoding when mode is "text"

---

#### Python

**`Create a new file`**

```python Create a new file
instance.file(command="create", path="new_file.txt", content="New file content")
```

#### TypeScript

**`Create a new file`**

```typescript Create a new file
await instance.file({command: "create", path: "new_file.txt", content: "New file content"});
```

#### `replace`

Replace a string in a file

**`path`** `string` — required

Path to the file

---

**`old_str`** `string` — required

String to replace

---

**`new_str`** `string` — required

Replacement string

---

**`all_occurrences`** `boolean` — default: false

Replace all occurrences if true, only first occurrence if false

---

#### Python

**`Replace first occurrence`**

```python Replace first occurrence
instance.file(command="replace", path="my_file.txt", old_str="old text", new_str="new text")
```

**`Replace all occurrences`**

```python Replace all occurrences
instance.file(command="replace", path="my_file.txt", old_str="old text", new_str="new text", all_occurrences=True)
```

#### TypeScript

**`Replace first occurrence`**

```typescript Replace first occurrence
await instance.file({command: "replace", path: "my_file.txt", oldStr: "old text", newStr: "new text"});
```

**`Replace all occurrences`**

```typescript Replace all occurrences
await instance.file({command: "replace", path: "my_file.txt", oldStr: "old text", newStr: "new text", allOccurrences: true});
```

#### `insert`

Insert text at a specific line in a file

**`path`** `string` — required

Path to the file

---

**`line`** `number` — required

Line number to insert at (1-based)

---

**`text`** `string` — required

Text to insert

---

#### Python

**`Insert at line`**

```python Insert at line
instance.file(command="insert", path="my_file.txt", line=2, text="New line content")
```

#### TypeScript

**`Insert at line`**

```typescript Insert at line
await instance.file({command: "insert", path: "my_file.txt", line: 2, text: "New line content"});
```

#### `delete_lines`

Delete specified lines from a file

**`path`** `string` — required

Path to the file

---

**`lines`** `array` — required

Array of line numbers to delete (1-based)

---

#### Python

**`Delete specific lines`**

```python Delete specific lines
instance.file(command="delete_lines", path="my_file.txt", lines=[2, 5, 10])
```

#### TypeScript

**`Delete specific lines`**

```typescript Delete specific lines
await instance.file({command: "delete_lines", path: "my_file.txt", lines: [2, 5, 10]});
```

#### `undo`

Undo the last text editing operation on a file

**`path`** `string` — required

Path to the file

---

#### Python

**`Undo last edit`**

```python Undo last edit
instance.file(command="undo", path="my_file.txt")
```

#### TypeScript

**`Undo last edit`**

```typescript Undo last edit
await instance.file({command: "undo", path: "my_file.txt"});
```

#### `grep`

Search for a pattern in a file or directory

**`pattern`** `string` — required

Regular expression pattern to search for

---

**`path`** `string` — required

Path to file or directory to search

---

**`case_sensitive`** `boolean` — default: true

Whether search is case sensitive

---

**`recursive`** `boolean` — default: false

Search directories recursively (required for directory paths)

---

**`line_numbers`** `boolean` — default: true

Include line numbers in results

---

#### Python

**`Search in file`**

```python Search in file
results = instance.file(command="grep", path="my_file.txt", pattern="search term")
```

**`Recursive search in directory`**

```python Recursive search in directory
results = instance.file(command="grep", path="my_directory", pattern="search term", 
                            recursive=True, case_sensitive=False)
```

#### TypeScript

**`Search in file`**

```typescript Search in file
const results = await instance.file({command: "grep", path: "my_file.txt", pattern: "search term"});
```

**`Recursive search in directory`**

```typescript Recursive search in directory
const results = await instance.file({command: "grep", path: "my_directory", pattern: "search term", 
                                        recursive: true, caseSensitive: false});
```

### `upload`

Upload a file to the instance

**`file`** `File` — required

The file to upload, can be a file object, bytes, or string

---

**`path`** `string` — required

Destination path on the instance

---

#### Python

```python
# Upload a file from local path
with open("local_file.txt", "rb") as f:
    response = instance.upload(file=f, path="uploaded_file.txt")

# Upload string content as a file
instance.upload(file="Hello World", path="hello.txt")

# Upload with explicit filename and content type
instance.upload(
    file=("myfile.txt", "File content", "text/plain"),
    path="myfile.txt"
)
```

#### TypeScript

```typescript
// Upload a file
const file = new File(["file content"], "filename.txt", { type: "text/plain" });
const response = await instance.upload(file, { path: "uploaded_file.txt" });

// Upload a Blob
const blob = new Blob(["Hello World"], { type: "text/plain" });
await instance.upload(blob, { path: "hello.txt" });
```

### `stop`

Stop the instance

#### Python

`python instance.stop() `

#### TypeScript

`typescript await instance.stop(); `

### `pause`

Pause the instance

#### Python

`python instance.pause() `

#### TypeScript

`typescript await instance.pause(); `

### `resume`

Resume the instance

#### Python

**`Resume with default timeout`**

```python Resume with default timeout
instance.resume()
```

**`Resume with custom timeout`**

```python Resume with custom timeout
instance.resume(timeout_hours=2.5)
```

#### TypeScript

**`Resume with default timeout`**

```typescript Resume with default timeout
await instance.resume();
```

**`Resume with custom timeout`**

```typescript Resume with custom timeout
await instance.resume({timeoutHours: 2.5});
```

## Compatible tools

* `BashTool`
* `ComputerTool`
* `EditTool`

## Screen resolution

By default, the Ubuntu instance runs at 1024x768 resolution. You can specify a custom resolution when starting the instance:

#### Python

```python
instance = client.start_ubuntu(resolution=[1920, 1080])
```

#### TypeScript

```typescript
const instance = await client.startUbuntu({resolution: [1920, 1080]});
```

## Additional protocols

The Ubuntu instance supports several protocols that provide additional functionality:

* [Browser](/protocols/browser) - Control the browser with Playwright
* [Code Execution](/protocols/code) - Execute code in Python and JavaScript
* [Environment Variables](/protocols/env) - Manage environment variables

> Deploy an Ubuntu instance

## Docs

- [Browser](https://docs.scrapybara.com/protocols/browser.md): Control a browser directly in your Scrapybara instance with Playwright
- [Code Execution](https://docs.scrapybara.com/protocols/code.md): Execute code in your Scrapybara instance
- [Environment Variables](https://docs.scrapybara.com/protocols/env.md): Manage environment variables in your Scrapybara instance