Skip to main content
A desktop sandbox is a secure, isolated virtual desktop for building and testing computer use agents. It lets an agent securely interact with desktop applications through controlled virtualization. The desktop is exposed as a stream that a browser can open.
Install the SDK, or the CLI for ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.

Set up the SDK

1

Set the environment variables

Set two environment variables before running any example. Replace <your-api-key> with a key from the API Keys page of the console.
The SDK and the CLI read both variables from the environment.
string
Authenticates requests to Agent Sandbox.
string
Selects the Agent Sandbox service for ppio.ai. Without it, the SDK and the CLI connect to their built-in default service instead.
These commands set the variables for the current terminal session only.
2

Install the SDK

Install the SDK for the language used: pip install ppio-sandbox for Python, or npm i ppio-sandbox for Node.js.
The desktop helpers are in ppio_sandbox.desktop in Python and ppio-sandbox/desktop in Node.js.

Run a desktop session

1

Create the desktop sandbox and start the stream

create() initializes a virtual desktop sandbox and accepts a timeout in Python or timeoutMs in Node.js for the sandbox lifetime. stream.start() activates desktop streaming.
2

Read the interactive and view-only URLs

stream.get_url() or getUrl() returns the browser URL. The interactive URL accepts input; the view-only URL disables interaction and suits monitoring.
3

Stop the stream and kill the sandbox

The example keeps the program running until Ctrl+C or a bounded wait ends, then stops the stream and kills the sandbox. The Node.js example stops the stream and kills the sandbox inside its cleanup function.

Full example

Last modified on November 19, 2026