Ubuntu

Deploy an Ubuntu instance

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

1instance = client.start_ubuntu()

Available actions

screenshot

Take a base64 encoded image of the current desktop

1base_64_image = instance.screenshot().base_64_image

get_stream_url

Get the interactive stream URL

1stream_url = instance.get_stream_url().stream_url

computer

Perform computer actions with the mouse and keyboard

move_mouse

Move mouse cursor to specific coordinates

coordinates
arrayRequired

[x, y] coordinates to move to

hold_keys
array

List of modifier keys to hold during the action

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

Move mouse
1instance.computer(action="move_mouse", coordinates=[100, 200])
Move mouse while holding shift
1instance.computer(action="move_mouse", coordinates=[100, 200], hold_keys=["shift"])
Move mouse without taking a screenshot
1instance.computer(action="move_mouse", coordinates=[100, 200], screenshot=False)

click_mouse

Perform a mouse click at current position or specified coordinates

button
stringRequired

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

click_type
stringDefaults to click

Type of click action (“down”, “up”, “click”)

coordinates
array

[x, y] coordinates to click at

num_clicks
numberDefaults to 1

Number of clicks

hold_keys
array

List of modifier keys to hold during the action

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

Left click at current position
1instance.computer(action="click_mouse", button="left")
Right click at coordinates
1instance.computer(action="click_mouse", button="right", coordinates=[300, 400])
Mouse down
1instance.computer(action="click_mouse", button="left", click_type="down")
Double click at coordinates
1instance.computer(action="click_mouse", button="left", num_clicks=2, coordinates=[500, 300])

drag_mouse

Click and drag from current position to specified coordinates

path
arrayRequired

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

hold_keys
array

List of modifier keys to hold during the action

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

Drag to coordinates
1instance.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
numberDefaults to 0

Horizontal scroll amount

delta_y
numberDefaults to 0

Vertical scroll amount

hold_keys
array

List of modifier keys to hold during the action

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

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

press_key

Press a key or combination of keys. Scrapybara supports keys defined by X keysyms. Common aliases are also supported:

  • altAlt_L
  • ctrl, controlControl_L
  • metaMeta_L
  • superSuper_L
  • shiftShift_L
keys
arrayRequired

List of keys to press

duration
number

Time to hold keys in seconds

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

Press ctrl+c
1instance.computer(action="press_key", keys=["ctrl", "c"])
Hold shift for 2 seconds
1instance.computer(action="press_key", keys=["shift"], duration=2)
Press enter/return
1instance.computer(action="press_key", keys=["Return"])

type_text

Type text into the active window

text
stringRequired

Text to type

hold_keys
array

List of modifier keys to hold while typing

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

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

wait

Wait for a specified duration

duration
numberRequired

Time to wait in seconds

screenshot
booleanDefaults to true

Whether to take a screenshot after the action

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

take_screenshot

Take a screenshot of the desktop

1screenshot = instance.computer(action="take_screenshot").base_64_image

get_cursor_position

Get current mouse cursor coordinates

1cursor_position = instance.computer(action="get_cursor_position").output

bash

Run a bash command

Run a bash command
1output = instance.bash(command="ls -la")
Restart the shell
1instance.bash(restart=True)
Get information about background processes
1background_processes = instance.bash(get_background_processes=True)
2# Returns a dictionary of PIDs with their status and command:
3# {pid: {"status": True/False, "command": "original command"}}

edit

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

Edit a file on the instance

Create a new file
1instance.edit(command="create", path="hello.txt", file_text="Hello world")
Replace text in a file
1instance.edit(command="str_replace", path="hello.txt", old_str="Hello", new_str="Hi")
Insert text at a specific line
1instance.edit(command="insert", path="hello.txt", insert_line=2, file_text="New line")

file

Manage files and directories on the instance

read

Read the content of a file in text or binary mode

path
stringRequired

Path to the file to read

mode
stringDefaults to text

Read mode: “text” or “binary”

encoding
stringDefaults to utf-8

Text encoding when mode is “text”

Read text file
1content = instance.file(command="read", path="my_file.txt")
Read binary file
1binary_content = instance.file(command="read", path="image.png", mode="binary")

write

Write content to a file, overwriting if it exists

path
stringRequired

Path to the file to write

content
stringRequired

Content to write to the file

mode
stringDefaults to text

Write mode: “text” or “binary” (base64 encoded for binary)

encoding
stringDefaults to utf-8

Text encoding when mode is “text”

Write text to file
1instance.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
stringRequired

Path to the file to append to

content
stringRequired

Content to append to the file

mode
stringDefaults to text

Append mode: “text” or “binary” (base64 encoded for binary)

encoding
stringDefaults to utf-8

Text encoding when mode is “text”

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

exists

Check if a path exists

path
stringRequired

Path to check

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

list

List the contents of a directory

path
stringRequired

Path to the directory to list

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

mkdir

Create a directory, including parent directories if needed

path
stringRequired

Path to the directory to create

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

rmdir

Remove an empty directory

path
stringRequired

Path to the directory to remove

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

delete

Delete a file or directory

path
stringRequired

Path to delete

recursive
booleanDefaults to false

Delete directory contents recursively

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

move

Move or rename a file or directory

src
stringRequired

Source path

dst
stringRequired

Destination path

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

copy

Copy a file or directory

src
stringRequired

Source path

dst
stringRequired

Destination path

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

view

View file content with line numbers or list directory contents

path
stringRequired

Path to view

view_range
array

Optional [start, end] line range to view

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

create

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

path
stringRequired

Path to the file to create

content
stringRequired

Content to write to the new file

mode
stringDefaults to text

Create mode: “text” or “binary” (base64 encoded for binary)

encoding
stringDefaults to utf-8

Text encoding when mode is “text”

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

replace

Replace a string in a file

path
stringRequired

Path to the file

old_str
stringRequired

String to replace

new_str
stringRequired

Replacement string

all_occurrences
booleanDefaults to false

Replace all occurrences if true, only first occurrence if false

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

insert

Insert text at a specific line in a file

path
stringRequired

Path to the file

line
numberRequired

Line number to insert at (1-based)

text
stringRequired

Text to insert

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

delete_lines

Delete specified lines from a file

path
stringRequired

Path to the file

lines
arrayRequired

Array of line numbers to delete (1-based)

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

undo

Undo the last text editing operation on a file

path
stringRequired

Path to the file

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

grep

Search for a pattern in a file or directory

pattern
stringRequired

Regular expression pattern to search for

path
stringRequired

Path to file or directory to search

case_sensitive
booleanDefaults to true

Whether search is case sensitive

recursive
booleanDefaults to false

Search directories recursively (required for directory paths)

line_numbers
booleanDefaults to true

Include line numbers in results

Search in file
1results = instance.file(command="grep", path="my_file.txt", pattern="search term")
Recursive search in directory
1results = instance.file(command="grep", path="my_directory", pattern="search term",
2 recursive=True, case_sensitive=False)

stop

Stop the instance

1instance.stop()

pause

Pause the instance

1instance.pause()

resume

Resume the instance

Resume with default timeout
1instance.resume()
Resume with custom timeout
1instance.resume(timeout_hours=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:

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

Additional protocols

The Ubuntu instance supports several protocols that provide additional functionality: