For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordDashboard
DocumentationAPI ReferenceCookbook
DocumentationAPI ReferenceCookbook
  • Get Started
    • Introduction
    • Quickstart
    • Best Practices
  • Guides
    • Act SDK
    • Auth States
    • Conversations
    • Tools
  • Providers
    • OpenAI
    • Anthropic
  • Instances
    • Ubuntu
      • Browser
      • Code Execution
      • Environment Variables
    • Browser
    • Windows
  • Resources
    • Starter Templates
    • Cursor Rules
    • Cookbook
Logo
DiscordDashboard
On this page
  • UbuntuInstance
  • Start an Ubuntu instance
  • Available actions
  • screenshot
  • get_stream_url
  • computer
  • move_mouse
  • click_mouse
  • drag_mouse
  • scroll
  • press_key
  • type_text
  • wait
  • take_screenshot
  • get_cursor_position
  • bash
  • edit
  • file
  • read
  • write
  • append
  • exists
  • list
  • mkdir
  • rmdir
  • delete
  • move
  • copy
  • view
  • create
  • replace
  • insert
  • delete_lines
  • undo
  • grep
  • upload
  • stop
  • pause
  • resume
  • Compatible tools
  • Screen resolution
  • Additional protocols
Instances

Ubuntu

Deploy an Ubuntu instance
Was this page helpful?
Previous

Browser

Control a browser directly in your Scrapybara instance with Playwright
Next
Built with

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
TypeScript
python instance = client.start_ubuntu()

Available actions

screenshot

Take a base64 encoded image of the current desktop

Python
TypeScript

python base_64_image = instance.screenshot().base_64_image

get_stream_url

Get the interactive stream URL

Python
TypeScript

python stream_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

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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:

  • alt → Alt_L
  • ctrl, control → Control_L
  • meta → Meta_L
  • super → Super_L
  • shift → Shift_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

Python
TypeScript
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

Python
TypeScript
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

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

take_screenshot

Take a screenshot of the desktop

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

get_cursor_position

Get current mouse cursor coordinates

Python
TypeScript
1cursor_position = 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
TypeScript
Run a bash command
1output = instance.bash(command="ls -la")
Run a command in a specific session
1output = instance.bash(command="ls -la", session=1)
Run a command with custom timeout
1output = instance.bash(command="sleep 30", timeout=60)
Restart a session
1instance.bash(restart=True, session=1)
List available bash sessions
1sessions = instance.bash(list_sessions=True)
Check the status of a session
1session_exists = instance.bash(check_session=1)

edit

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

Edit a file on the instance

Python
TypeScript
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”

Python
TypeScript
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”

Python
TypeScript
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”

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

exists

Check if a path exists

path
stringRequired

Path to check

Python
TypeScript
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

Python
TypeScript
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

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

rmdir

Remove an empty directory

path
stringRequired

Path to the directory to remove

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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”

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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)

Python
TypeScript
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

Python
TypeScript
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

Python
TypeScript
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)

upload

Upload a file to the instance

file
FileRequired

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

path
stringRequired

Destination path on the instance

Python
TypeScript
1# Upload a file from local path
2with open("local_file.txt", "rb") as f:
3    response = instance.upload(file=f, path="uploaded_file.txt")
4
5# Upload string content as a file
6instance.upload(file="Hello World", path="hello.txt")
7
8# Upload with explicit filename and content type
9instance.upload(
10    file=("myfile.txt", "File content", "text/plain"),
11    path="myfile.txt"
12)

stop

Stop the instance

Python
TypeScript
python instance.stop()

pause

Pause the instance

Python
TypeScript
python instance.pause()

resume

Resume the instance

Python
TypeScript
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:

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

Additional protocols

The Ubuntu instance supports several protocols that provide additional functionality:

  • Browser - Control the browser with Playwright
  • Code Execution - Execute code in Python and JavaScript
  • Environment Variables - Manage environment variables