Computer tools

Screenshots, input, windows, files and shell on a sandbox desktop.

Tool	Description
`computer_screenshot`	Take a screenshot (long edge at most 1200 px).
`computer_click`	Click at screenshot coordinates.
`computer_double_click`	Double-click at screenshot coordinates.
`computer_move_cursor`	Move the cursor.
`computer_mouse_down`	Press a mouse button.
`computer_mouse_up`	Release a mouse button.
`computer_type`	Type text.
`computer_key`	Press a key (enter, escape, tab, a, ...).
`computer_key_down`	Hold a key.
`computer_key_up`	Release a key.
`computer_hotkey`	Press a shortcut such as ctrl+c or cmd+shift+s.
`computer_scroll`	Scroll up, down, left or right.
`computer_drag`	Drag between two points.
`computer_clipboard_get`	Read clipboard text.
`computer_clipboard_set`	Set clipboard text.
`computer_file_read`	Read a text file.
`computer_file_write`	Write a text file (the Spaces `space_write` implementation, on this sandbox).
`computer_file_list`	List a directory.
`computer_shell`	Run a shell command (sh -c, 120 s timeout; the Spaces `space_bash` implementation, on this sandbox).
`computer_window_list`	List windows.
`computer_window_open`	Open a file or URL.
`computer_window_focus`	Focus a window.
`computer_window_unfocus`	Remove focus from the current window (Escape).
`computer_window_minimize`	Minimize a window.
`computer_window_maximize`	Maximize a window.
`computer_window_close`	Close a window.
`computer_window_resize`	Resize a window.
`computer_window_move`	Move a window.
`computer_window_get_info`	Get a window's title, position and size.
`computer_launch`	Launch an application.
`computer_get_screen_size`	Primary display size in points.
`computer_get_cursor_position`	Cursor position in points.
`computer_get_current_window`	The focused window's id and title.
`computer_get_accessibility_tree`	Accessibility tree of the focused (or given) window.
`computer_accessibility_act`	Act on an accessibility element (press, focus, set_value, ...).

Computer tools act on a sandbox desktop through its cua-spacesd. Coordinates are in the pixel space of the last computer_screenshot of that sandbox.

Served by cua mcp; see MCP tools for every tool.

`computer_screenshot`#

Take a screenshot (long edge at most 1200 px). Later coordinates are in its pixel space.

Permission: computer:screenshot.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_click`#

Click at screenshot coordinates.

Permission: computer:click.

Parameter	Type	Default	Description
`button`	`string`		left (default), right or middle.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_double_click`#

Double-click at screenshot coordinates.

Permission: computer:click.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_move_cursor`#

Move the cursor.

Permission: computer:click.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_mouse_down`#

Press a mouse button.

Permission: computer:click.

Parameter	Type	Default	Description
`button`	`string`		left, right or middle.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_mouse_up`#

Release a mouse button.

Permission: computer:click.

Parameter	Type	Default	Description
`button`	`string`		left, right or middle.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_type`#

Type text.

Permission: computer:type.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`text`	`string`	required	Text.

Example arguments

{"text":"<text>"}

`computer_key`#

Press a key (enter, escape, tab, a, ...).

Permission: computer:key.

Parameter	Type	Default	Description
`key`	`string`	required	Key.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"key":"<key>"}

`computer_key_down`#

Hold a key.

Permission: computer:key.

Parameter	Type	Default	Description
`key`	`string`	required	Key.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"key":"<key>"}

`computer_key_up`#

Release a key.

Permission: computer:key.

Parameter	Type	Default	Description
`key`	`string`	required	Key.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"key":"<key>"}

`computer_hotkey`#

Press a shortcut such as ctrl+c or cmd+shift+s.

Permission: computer:hotkey.

Parameter	Type	Default	Description
`keys`	`string`	required	Keys joined by +.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"keys":"<keys>"}

`computer_scroll`#

Scroll up, down, left or right.

Permission: computer:scroll.

Parameter	Type	Description
`amount`	`integer`	Lines (default 3).
`direction`	`string`	down (default), up, left, right.
`sandbox`	`string`	Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_drag`#

Drag between two points.

Permission: computer:drag.

Parameter	Type	Default	Description
`end_x`	`integer`	required	End X.
`end_y`	`integer`	required	End Y.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`start_x`	`integer`	required	Start X.
`start_y`	`integer`	required	Start Y.

Example arguments

{"start_x":100,"start_y":200,"end_x":100,"end_y":200}

`computer_clipboard_get`#

Read clipboard text.

Permission: computer:clipboard.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_clipboard_set`#

Set clipboard text.

Permission: computer:clipboard.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`text`	`string`	required	Text.

Example arguments

{"text":"<text>"}

`computer_file_read`#

Read a text file.

Permission: computer:file.

Parameter	Type	Default	Description
`path`	`string`	required	Path.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"path":"<path>"}

`computer_file_write`#

Write a text file (the Spaces space_write implementation, on this sandbox).

Permission: computer:file.

Parameter	Type	Default	Description
`content`	`string`	required	Content.
`path`	`string`	required	Path.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"path":"<path>","content":"<content>"}

`computer_file_list`#

List a directory.

Permission: computer:file.

Parameter	Type	Default	Description
`path`	`string`		Path (default .).
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_shell`#

Run a shell command (sh -c, 120 s timeout; the Spaces space_bash implementation, on this sandbox).

Permission: computer:shell.

Parameter	Type	Default	Description
`command`	`string`	required	Command line.
`sandbox`	`string`		Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"command":"<command>"}