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

# Computer Use

***PPIO Desktop*** 是一个专为开发 Computer Use Agent 打造的安全虚拟桌面框架。该方案提供全面且隔离的桌面环境,使 AI Agent 能够通过受控的虚拟化安全地与桌面应用交互。本文档将详细介绍如何在 PPIO Sandbox 服务上运行它。

***

### 1. 获取 PPIO API Key

### 2. 环境配置

在开始使用该服务之前,你需要配置必要的环境变量:

```bash theme={null}
export PPIO_API_KEY=<Your API key obtained in the previous step>
```

### 3. 安装 SDK

根据你的开发环境和编程语言,选择相应的安装方式:

```bash theme={null}
npm i ppio-sandbox
```

```bash theme={null}
pip install ppio-sandbox
```

### 4. 实现示例

#### 获取虚拟桌面流 VNC URL

以下实现演示了如何实例化虚拟桌面环境,并获取用于远程桌面交互的 VNC 访问端点:

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

  ppio = PPIO()

  # 初始化虚拟桌面 Sandbox 实例
  desktop = ppio.desktop.create()

  # 启动桌面流服务
  desktop.stream.start()

  # 获取交互式 VNC 端点 URL
  url = desktop.stream.get_url()
  print(url)
  # 预期输出格式：
  # 可通过浏览器访问的交互式虚拟桌面会话 URL，适合应用集成。
  # https://6080-ik0n7lc3j0dvqd4jxy6g7.cn-beijing-1.sandbox.ppio.com/vnc.html?autoconnect=true&resize=scale

  # 获取只读 VNC 端点 URL（禁用交互）
  url_readonly = desktop.stream.get_url(view_only=True)
  print(url_readonly)
  # 预期输出格式：
  # 可通过浏览器访问的只读虚拟桌面会话 URL（非交互模式），适合监控类应用。
  # https://6080-ik0n7lc3j0dvqd4jxy6g7.cn-beijing-1.sandbox.ppio.com/vnc.html?autoconnect=true&view_only=true&resize=scale

  # 实现键盘中断处理以优雅退出
  try:
      print('Desktop stream started, press Ctrl+C to stop the program...')
      import time
      while True:
          time.sleep(0.1)
  except KeyboardInterrupt:
      print('\nProgram interrupted, cleaning up resources...')

  # 执行资源释放流程
  desktop.stream.stop()  # Terminate streaming service
  desktop.kill()  # Deallocate sandbox instance
  ```

  ```javascript JavaScript & TypeScript theme={null}
  // demo.ts 实现
  import { PPIO } from 'ppio-sandbox'

  const ppio = new PPIO()

  async function main() {

    // 初始化虚拟桌面 Sandbox 实例
    const desktop = await ppio.desktop.create()

    // 启动桌面流服务
    await desktop.stream.start()

    // 获取交互式 VNC 端点 URL
    const url = desktop.stream.getUrl()
    console.log(url)

    // 预期输出格式：
    // 可通过浏览器访问的交互式虚拟桌面会话 URL，适合应用集成。
    // https://6080-ik0n7lc3j0dvqd4jxy6g7.cn-beijing-1.sandbox.ppio.com/vnc.html?autoconnect=true&resize=scale

    // 获取只读 VNC 端点 URL（禁用交互）
    const urlDisabledInteraction = desktop.stream.getUrl({ viewOnly: true })
    console.log(urlDisabledInteraction)
    // 预期输出格式：
    // 可通过浏览器访问的只读虚拟桌面会话 URL（非交互模式），适合监控类应用。
    // https://6080-ik0n7lc3j0dvqd4jxy6g7.cn-beijing-1.sandbox.ppio.com/vnc.html?autoconnect=true&view_only=true&resize=scale

    // 保持程序运行
    console.log('Desktop stream started, press Ctrl+C to stop the program...')
    const interval = setInterval(() => {}, 1000)

    // 注册中断信号处理器以清理资源
    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() // Deallocate sandbox instance
      } catch (err) {
        console.error('Error cleaning up resources:', err)
      }
      process.exit(0)
    }

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

  main().catch(console.error)
  ```
</CodeGroup>

运行示例:

<img src="https://mintcdn.com/ppinfra/nkBi88UBzmHnrrPQ/images/sandbox/computer-use-vnc-url.jpg?fit=max&auto=format&n=nkBi88UBzmHnrrPQ&q=85&s=253481b30430e828b1615e9342cd23c6" alt="运行示例输出的 VNC 访问链接" width="3340" height="172" data-path="images/sandbox/computer-use-vnc-url.jpg" />

访问虚拟桌面流 VNC URL:

<img src="https://mintcdn.com/ppinfra/nkBi88UBzmHnrrPQ/images/sandbox/computer-use-desktop.jpg?fit=max&auto=format&n=nkBi88UBzmHnrrPQ&q=85&s=df66849efdf4569769d69ed82fdcbf72" alt="PPIO Sandbox 虚拟桌面操作界面" width="5120" height="3824" data-path="images/sandbox/computer-use-desktop.jpg" />