> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a desktop sandbox for computer use

> Start a desktop sandbox, activate its desktop stream, and read interactive or view-only VNC URLs that open in a browser for computer use agents.

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.

> [!NOTE]
>
> 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](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## 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](https://console.ppio.ai/api-keys).

> [tab] macOS and Linux
>
> ```bash theme={null}
> export PPIO_API_KEY="<your-api-key>"
> export PPIO_DOMAIN="sandbox.ppio.ai"
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> $env:PPIO_API_KEY = "<your-api-key>"
> $env:PPIO_DOMAIN = "sandbox.ppio.ai"
> ```

The SDK and the CLI read both variables from the environment.

**PPIO\_API\_KEY** `string`

Authenticates requests to Agent Sandbox.

**PPIO\_DOMAIN** `string`

Selects the Agent Sandbox service for ppio.ai. Without it, the SDK and the CLI connect to their built-in default service instead.

> [!NOTE]
>
> 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.

```python Python theme={null}
# Initialize a virtual desktop sandbox
desktop = ppio.desktop.create(timeout=3600)

# Activate desktop streaming service
desktop.stream.start()
```

```javascript Node.js theme={null}
// Initialize a virtual desktop sandbox
const desktop = await ppio.desktop.create({ timeoutMs: 3_600_000 })

// Activate desktop streaming service
await desktop.stream.start()
```

**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.

```python Python theme={null}
# Retrieve interactive VNC endpoint URL
url = desktop.stream.get_url()
print(url)
# Browser-accessible URL for interactive virtual desktop session. Suitable for application integration.

# Retrieve read-only VNC endpoint URL (interaction disabled)
url_readonly = desktop.stream.get_url(view_only=True)
print(url_readonly)
# Browser-accessible URL for view-only virtual desktop session (non-interactive mode). Suitable for monitoring applications.
```

```javascript Node.js theme={null}
// Retrieve interactive VNC endpoint URL
const url = desktop.stream.getUrl()
console.log(url)
// Browser-accessible URL for interactive virtual desktop session. Suitable for application integration.

// Retrieve read-only VNC endpoint URL (interaction disabled)
const urlDisabledInteraction = desktop.stream.getUrl({ viewOnly: true })
console.log(urlDisabledInteraction)
// Browser-accessible URL for view-only virtual desktop session (non-interactive mode). Suitable for monitoring applications.
```

**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.

```python Python theme={null}
# Execute resource deallocation procedures
desktop.stream.stop()  # Terminate streaming service
desktop.kill()  # Kill the sandbox
```

```javascript Node.js theme={null}
    await desktop.stream.stop() // Terminate streaming service
    await desktop.kill() // Kill the sandbox
```

### Full example

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

# Initialize a virtual desktop sandbox
desktop = ppio.desktop.create(timeout=3600)

# Activate desktop streaming service
desktop.stream.start()

# Retrieve interactive VNC endpoint URL
url = desktop.stream.get_url()
print(url)
# Browser-accessible URL for interactive virtual desktop session. Suitable for application integration.

# Retrieve read-only VNC endpoint URL (interaction disabled)
url_readonly = desktop.stream.get_url(view_only=True)
print(url_readonly)
# Browser-accessible URL for view-only virtual desktop session (non-interactive mode). Suitable for monitoring applications.

# Implement keyboard interrupt handling for graceful shutdown
try:
    print('Desktop stream started, press Ctrl+C to stop the program...')
    import time
    for _ in range(10):
        time.sleep(1)
except KeyboardInterrupt:
    print('\nProgram interrupted, cleaning up resources...')

# Execute resource deallocation procedures
desktop.stream.stop()  # Terminate streaming service
desktop.kill()  # Kill the sandbox
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// Initialize a virtual desktop sandbox
const desktop = await ppio.desktop.create({ timeoutMs: 3_600_000 })

// Activate desktop streaming service
await desktop.stream.start()

// Retrieve interactive VNC endpoint URL
const url = desktop.stream.getUrl()
console.log(url)
// Browser-accessible URL for interactive virtual desktop session. Suitable for application integration.

// Retrieve read-only VNC endpoint URL (interaction disabled)
const urlDisabledInteraction = desktop.stream.getUrl({ viewOnly: true })
console.log(urlDisabledInteraction)
// Browser-accessible URL for view-only virtual desktop session (non-interactive mode). Suitable for monitoring applications.

// Keep the program running for a bounded time
console.log('Desktop stream started, press Ctrl+C to stop the program...')
const interval = setInterval(() => {}, 1000)

// Register interrupt signal handlers for resource cleanup
let isCleaning = false
const cleanup = async () => {
  if (isCleaning) return
  isCleaning = true

  console.log('\nProgram interrupted, cleaning up resources...')
  clearInterval(interval)
  try {
    await desktop.stream.stop() // Terminate streaming service
    await desktop.kill() // Kill the sandbox
  } catch (err) {
    console.error('Error cleaning up resources:', err)
  }
  process.exit(0)
}

process.on('SIGINT', cleanup)
process.on('SIGTERM', cleanup)

// Run the same cleanup when the bounded wait finishes
setTimeout(cleanup, 5_000)
```


## Related topics

- [Run commands in a sandbox](https://docs.ppio.ai/sandbox/commands.md)
- [Connect to a running sandbox](https://docs.ppio.ai/sandbox/connect.md)
- [ppio sandbox exec](https://docs.ppio.ai/sandbox/cli/exec.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.