Create a fresh, disposable Linux computer (a "sandbox") and wait until it is ready to use.

Use this before running untrusted code, installing packages, or trying anything you would not want to do on the user's real computer. Every sandbox starts from the same clean state and is completely separate from the user's machine and from other sandboxes.

network: "none" (default) gives the sandbox no network at all. Choose another mode only when the task needs to download something:

• "web": internet for web downloads only (HTTP and HTTPS), and nothing else: the user's own computer and home network stay unreachable. Prefer this. Standard tools (curl, wget, pip, git over https) work as usual; with sudo use sudo -E, for example sudo -E apt-get -y install <package>. ping and non-web protocols do not work. It may not be set up on this computer; the error will say so.

• "nat": full internet access. It can also reach the user's own computer and home network, so never use it for code you do not trust.

Takes up to a few minutes. Returns the sandbox_id to pass to the other sandbox tools. Destroy the sandbox with sandbox_destroy when you are finished.

Run a shell command inside a sandbox and return what it printed.

Use this to execute code, install packages, inspect files, or do anything else on the sandbox computer. The command is run by bash, so pipes, redirects, && and multi-line scripts all work. Each call starts in the home directory with a fresh shell: files persist between calls, but cd and environment variables do not. The command gets no keyboard input, so use non-interactive flags (for example apt-get -y).

timeout_seconds: how long the command may run (1 to 3600, default 60). When the limit is reached the command is killed and timed_out is true.

Returns stdout, stderr, exit_code (0 means success) and timed_out. Very long output is cut at 1 MB; stdout_truncated / stderr_truncated say when that happened.

Start a command in a sandbox that keeps running in the background, and return at once.

Use this for things that do not finish on their own or take very long: a web server, a database, a watcher, a long build or download. sandbox_run would wait for them and time out. After starting, use sandbox_run for other commands in the same sandbox (for example to talk to the server you started), sandbox_check to see its output and whether it is still running, and sandbox_stop to end it.

The command is run by bash, starting in the home directory, with no keyboard input. A sandbox can have at most 8 background commands running at once. Background commands end when the sandbox is destroyed.

Returns a job_id to pass to sandbox_check and sandbox_stop.

Look at a background command started with sandbox_start: is it still running, and what has it printed?

Returns status ("running", "exited" when it ended by itself, or "stopped" when it was killed), exit_code (only when status is "exited"; 0 means success), and stdout and stderr collected so far. If the output is longer than about 1 MB only the newest part is returned, and stdout_truncated / stderr_truncated say so. Calling this does not affect the command; call it again later to see newer output.

Stop a background command started with sandbox_start, together with any programs it started.

Use this when you no longer need the command, or to free one of the 8 background slots. Its output stays available through sandbox_check afterwards. Returns a short confirmation, which also says if the command had already ended.

Copy a file or a whole folder from the user's computer into a sandbox.

Use this to give the sandbox something to work on (a script, a dataset, a project folder). Only things inside the user's designated transfer folder can be copied; nothing else on the user's computer is reachable.

host_path: the file or folder to copy, relative to the transfer folder (for example "data/input.csv" or "myproject"). Paths that leave the transfer folder are rejected. guest_path: full destination path inside the sandbox. For a file, the path of the file itself (for example "/home/debian/input.csv"); its folder must already exist. For a folder, the path the folder should have (for example "/home/debian/myproject"); it is created if missing, and the folder's contents are placed inside it.

Folders are copied with everything in them. Files arrive without the executable flag (use chmod +x if needed). A folder that contains links is refused. Returns a short confirmation with the number of files and the size.

Copy a file or a whole folder from a sandbox to the user's computer.

Use this to save results (a report, a built program, a log, an output folder) before destroying the sandbox, since everything inside a sandbox is lost when it is destroyed. Things can only be written inside the user's designated transfer folder.

guest_path: full path of the file or folder inside the sandbox (for example "/home/debian/out.txt" or "/home/debian/build"). host_path: where to save it, relative to the transfer folder (for example "results/out.txt" or "results/build"). Missing folders are created; existing files with the same names are replaced. Paths that leave the transfer folder are rejected.

When copying a folder, its contents are placed inside host_path. Links and files whose names are not valid on the user's computer are left out; the reply says how many. Returns the full path where it was saved, the number of files and the size.

Take a picture of what is currently on a sandbox's screen.

Use this to see things that have no text output: a graphical program, a boot or error screen, or to check what the sandbox is displaying when a command seems stuck. For the output of commands, sandbox_run is faster and more precise.

Returns a PNG image of the sandbox's display at this moment. Positions in this image, counted in pixels from its top-left corner, are what sandbox_click expects.

Click the mouse at a position on a sandbox's screen.

Use this to operate graphical programs: press buttons, open menus, focus a text field before typing. First take a sandbox_screenshot, find the thing to click, and pass its position: x pixels from the left edge and y pixels from the top edge of that image. Take another screenshot afterwards to see the result; screens need a moment to react.

button: "left" (default), "right" or "middle". double: true for a double-click. Only works if the user has switched keyboard and mouse input on; the error says so otherwise. For anything that can be done with a command, sandbox_run is faster and more reliable.

Type text on a sandbox's keyboard, as if a person typed it.

The text goes to whatever has keyboard focus on the sandbox's screen, so click the right field first (sandbox_click) and check with sandbox_screenshot. A line break in the text presses Enter, a tab presses Tab. Only plain English keyboard characters can be typed (letters, digits, common symbols), at most 10,000 at a time. For shortcuts and special keys use sandbox_key.

Press a single key or a keyboard shortcut on a sandbox's keyboard.

keys: a key name, or modifiers and a key joined with "+". Examples: "Return", "Escape", "Tab", "ctrl+c", "ctrl+alt+t", "alt+F4", "shift+Tab", "super" (opens the desktop's application search). Modifiers: ctrl, alt, shift, super. Key names: Return, Escape, Tab, Backspace, Delete, Space, Up, Down, Left, Right, Home, End, PageUp, PageDown, Insert, F1 to F12, or any single character.

Shut down a sandbox and permanently delete it and everything inside it.

Use this as soon as you no longer need a sandbox; only a few can exist at once. Copy out any files you want to keep first, because this cannot be undone. Returns a short confirmation.

List the sandboxes that currently exist.

Use this to find a sandbox_id you lost track of, or to check whether old sandboxes should be destroyed. Returns one entry per sandbox with its sandbox_id, network mode ("none" or "nat"), status, and age in seconds. Returns an empty list if there are none.