E2B 桌面沙盒 - 用于计算机使用的开源虚拟机

E2B 桌面沙盒是一个开源的安全虚拟桌面，专为计算机使用而设计。它由 E2B 提供支持。

每个沙盒彼此隔离，并且可以根据您的需求自定义任何依赖项。

示例

SDK 示例

• 基础示例：
  • Python
  • JavaScript
• 流式传输桌面应用程序：
  • Python
  • JavaScript

Open Computer Use

• 使用 100% 开源大模型实现的计算机使用场景。

🏄 Surf

• 基于 E2B 桌面沙盒的 OpenAI 计算机使用代理。以 Next.js 应用程序的形式运行。

🚀 快速开始

E2B 桌面沙盒构建在 E2B Sandbox 的基础上。

1. 获取 E2B API 密钥

在 E2B 上注册并获取您的 API 密钥。将您的 API 密钥设置为环境变量 E2B_API_KEY。

2. 安装 SDK

Python

pip install e2b-desktop

JavaScript

npm install @e2b/desktop

3. 创建桌面沙盒

Python

from e2b_desktop import Sandbox

# 创建一个新的桌面沙盒
desktop = Sandbox.create()

# 启动一个应用程序
desktop.launch('google-chrome')  # 或 vscode、firefox 等

# 等待 10 秒钟让应用程序打开
desktop.wait(10000)

# 流式传输应用程序窗口
# 注意：同一时间只能有一个流
# 在流式传输另一个应用程序之前，需要先停止当前的流
desktop.stream.start(
    window_id=desktop.get_current_window_id(), # 如果未提供，则会流式传输整个桌面
    require_auth=True
)

# 获取流的认证密钥
auth_key = desktop.stream.get_auth_key()

# 打印流的 URL
print('流 URL:', desktop.stream.get_url(auth_key=auth_key))

# 在任务完成后终止沙盒
# desktop.kill()

JavaScript

import { Sandbox } from '@e2b/desktop'

// 启动一个新的桌面沙盒
const desktop = await Sandbox.create()

// 启动一个应用程序
await desktop.launch('google-chrome') // 或 vscode、firefox 等

// 等待 10 秒钟让应用程序打开
await desktop.wait(10000)

// 流式传输应用程序窗口
// 注意：同一时间只能有一个流
// 在流式传输另一个应用程序之前，需要先停止当前的流
await desktop.stream.start({
  windowId: await desktop.getCurrentWindowId(), // 如果未提供，则会流式传输整个桌面
  requireAuth: true,
})

// 获取流的认证密钥
const authKey = desktop.stream.getAuthKey()

// 打印流的 URL
console.log('流 URL:', desktop.stream.getUrl({ authKey }))

// 在任务完成后终止沙盒
// await desktop.kill()

功能

流式传输桌面屏幕

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 开始流式传输
desktop.stream.start()

# 获取流的 URL
url = desktop.stream.get_url()
print(url)

# 获取流的 URL 并禁用用户交互
url = desktop.stream.get_url(view_only=True)
print(url)

# 停止流式传输
desktop.stream.stop()

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 开始流式传输
await desktop.stream.start()

// 获取流的 URL
const url = desktop.stream.getUrl()
console.log(url)

// 获取流的 URL 并禁用用户交互
const url = desktop.stream.getUrl({ viewOnly: true })
console.log(url)

// 停止流式传输
await desktop.stream.stop()

带密码保护的流式传输

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 开始流式传输
desktop.stream.start(
    require_auth=True  # 需要使用自动生成的密钥进行身份验证
)

# 获取身份验证密钥
auth_key = desktop.stream.get_auth_key()

# 获取流的 URL
url = desktop.stream.get_url(auth_key=auth_key)
print(url)

# 停止流式传输
desktop.stream.stop()

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 开始流式传输
await desktop.stream.start({
  requireAuth: true, // 需要使用自动生成的密钥进行身份验证
})

// 获取身份验证密钥
const authKey = await desktop.stream.getAuthKey()

// 获取流的 URL
const url = desktop.stream.getUrl({ authKey })
console.log(url)

// 停止流式传输
await desktop.stream.stop()

流式传输特定应用程序

[!WARNING]

• 如果目标应用程序尚未打开，将会抛出错误
• 一旦应用程序关闭，流式传输也会结束
• 不支持同时创建多个流式传输，您可能需要先停止当前的流，再为每个应用程序启动新的流

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 获取当前（活动）窗口 ID
window_id = desktop.get_current_window_id()

# 获取应用程序的所有窗口
window_ids = desktop.get_application_windows("Firefox")

# 开始流式传输
desktop.stream.start(window_id=window_ids[0])

# 停止流式传输
desktop.stream.stop()

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

# 获取当前（活动）窗口 ID
const windowId = await desktop.getCurrentWindowId()

# 获取应用程序的所有窗口
const windowIds = await desktop.getApplicationWindows('Firefox')

# 开始流式传输
await desktop.stream.start({ windowId: windowIds[0] })

# 停止流式传输
await desktop.stream.stop()

鼠标控制

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

desktop.double_click()
desktop.left_click()
desktop.left_click(x=100, y=200)
desktop.right_click()
desktop.right_click(x=100, y=200)
desktop.middle_click()
desktop.middle_click(x=100, y=200)
desktop.scroll(10) # 滚动指定的距离。正数向上滚动，负数向下滚动。
desktop.move_mouse(100, 200) # 移动到 x, y 坐标
desktop.drag((100, 100), (200, 200)) # 使用鼠标拖动
desktop.mouse_press("left") # 按下鼠标左键
desktop.mouse_release("left") # 释放鼠标左键

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

await desktop.doubleClick()
await desktop.leftClick()
await desktop.leftClick(100, 200)
await desktop.rightClick()
await desktop.rightClick(100, 200)
await desktop.middleClick()
await desktop.middleClick(100, 200)
await desktop.scroll(10) // 滚动指定的距离。正数向上滚动，负数向下滚动。
await desktop.moveMouse(100, 200) // 移动到 x, y 坐标
await desktop.drag([100, 100], [200, 200]) // 使用鼠标拖动
await desktop.mousePress('left') // 按下鼠标左键
await desktop.mouseRelease('left') // 释放鼠标左键

键盘控制

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 在当前光标位置写入文本，可自定义打字速度
desktop.write("Hello, world!")  # 默认：chunk_size=25, delay_in_ms=75
desktop.write("Fast typing!", chunk_size=50, delay_in_ms=25)  # 更快的打字速度

# 按键
desktop.press("enter")
desktop.press("space")
desktop.press("backspace")
desktop.press(["ctrl", "c"]) # 组合键

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 在当前光标位置写入文本，可自定义打字速度
await desktop.write('Hello, world!')
await desktop.write('Fast typing!', { chunkSize: 50, delayInMs: 25 }) // 更快的打字速度

// 按键
await desktop.press('enter')
await desktop.press('space')
await desktop.press('backspace')
await desktop.press(['ctrl', 'c']) // 组合键

窗口控制

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 获取当前（活动）窗口ID
window_id = desktop.get_current_window_id()

# 获取应用程序的所有窗口
window_ids = desktop.get_application_windows("Firefox")

# 获取窗口标题
title = desktop.get_window_title(window_id)

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 获取当前（活动）窗口ID
const windowId = await desktop.getCurrentWindowId()

// 获取应用程序的所有窗口
const windowIds = await desktop.getApplicationWindows('Firefox')

// 获取窗口标题
const title = await desktop.getWindowTitle(windowId)

截图

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 截取屏幕并保存为本地文件“screenshot.png”
image = desktop.screenshot()
# 将图像保存到文件
with open("screenshot.png", "wb") as f:
    f.write(image)

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()
const image = await desktop.screenshot()
// 将图像保存到文件
fs.writeFileSync('screenshot.png', image)

打开文件

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 使用默认应用打开文件
desktop.files.write("/home/user/index.js", "console.log('hello')") # 先创建文件
desktop.open("/home/user/index.js") # 再打开文件

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 使用默认应用打开文件
await desktop.files.write('/home/user/index.js', "console.log('hello')") // 先创建文件
await desktop.open('/home/user/index.js') // 再打开文件

启动应用

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 启动应用
desktop.launch('google-chrome')

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 启动应用
await desktop.launch('google-chrome')

运行任意 Bash 命令

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

# 运行任意 Bash 命令
out = desktop.commands.run("ls -la /home/user")
print(out)

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()

// 运行任意 Bash 命令
const out = await desktop.commands.run('ls -la /home/user')
console.log(out)

等待

Python

from e2b_desktop import Sandbox
desktop = Sandbox.create()

desktop.wait(1000) # 等待1秒

JavaScript

import { Sandbox } from '@e2b/desktop'

const desktop = await Sandbox.create()
await desktop.wait(1000) // 等待1秒

内部原理

目前，类桌面环境基于 Linux 和 Xfce。我们选择 Xfce 是因为它是一个快速、轻量级且广受欢迎、持续维护的环境。不过，该 Sandbox 模板完全可定制，您可以创建自己的桌面环境。 请在此处查看 Sandbox 模板的代码 here。

E2B Desktop Sandbox 快速上手指南

E2B Desktop Sandbox 是一个开源的安全虚拟桌面环境，专为“计算机使用（Computer Use）”场景设计。它允许开发者通过代码创建隔离的虚拟桌面，启动应用程序、控制鼠标键盘、截取屏幕或运行命令，非常适合构建 AI Agent 和自动化测试流程。

1. 环境准备

在开始之前，请确保满足以下要求：

• 操作系统：支持 Linux、macOS 或 Windows。
• 运行时环境：
  • Python 3.8+ 或 Node.js 18+
• E2B API Key：
  1. 访问 E2B 官网 注册账号。
  2. 获取您的 API Key。
  3. 设置环境变量（替换 <YOUR_API_KEY> 为您的实际密钥）：

     export E2B_API_KEY=<YOUR_API_KEY>
     

     (Windows PowerShell: $env:E2B_API_KEY="<YOUR_API_KEY>")

2. 安装步骤

根据您的开发语言选择对应的 SDK 进行安装。

Python

pip install e2b-desktop

(国内用户如遇下载缓慢，可使用清华源：pip install e2b-desktop -i https://pypi.tuna.tsinghua.edu.cn/simple)

JavaScript / TypeScript

npm install @e2b/desktop

(国内用户如遇下载缓慢，可使用淘宝镜像：npm install @e2b/desktop --registry=https://registry.npmmirror.com)

3. 基本使用

以下示例展示如何创建一个虚拟桌面沙箱，启动 Chrome 浏览器，并获取桌面的实时视频流地址。

Python 示例

from e2b_desktop import Sandbox

# 1. 创建一个新的桌面沙箱
desktop = Sandbox.create()

# 2. 启动应用程序 (例如：google-chrome, vscode, firefox)
desktop.launch('google-chrome')

# 3. 等待应用打开 (单位：毫秒)
desktop.wait(10000)

# 4. 开始流式传输当前窗口
# 注意：同一时间只能有一个活跃的视频流
desktop.stream.start(
    window_id=desktop.get_current_window_id(), 
    require_auth=True
)

# 5. 获取认证密钥和流媒体 URL
auth_key = desktop.stream.get_auth_key()
stream_url = desktop.stream.get_url(auth_key=auth_key)

print('Stream URL:', stream_url)
# 您可以在浏览器中打开此 URL 查看虚拟桌面

# 6. 任务完成后销毁沙箱
# desktop.kill()

JavaScript 示例

import { Sandbox } from '@e2b/desktop'

// 1. 创建一个新的桌面沙箱
const desktop = await Sandbox.create()

// 2. 启动应用程序
await desktop.launch('google-chrome')

// 3. 等待应用打开
await desktop.wait(10000)

// 4. 开始流式传输当前窗口
await desktop.stream.start({
  windowId: await desktop.getCurrentWindowId(),
  requireAuth: true,
})

// 5. 获取认证密钥和流媒体 URL
const authKey = await desktop.stream.getAuthKey()
const streamUrl = desktop.stream.getUrl({ authKey })

console.log('Stream URL:', streamUrl)

// 6. 任务完成后销毁沙箱
// await desktop.kill()

核心功能速览

创建沙箱后，您可以执行以下操作：

• 鼠标控制：desktop.left_click(x, y), desktop.move_mouse(x, y), desktop.scroll(amount)
• 键盘输入：desktop.write("Hello"), desktop.press("enter"), desktop.press(["ctrl", "c"])
• 截图：image = desktop.screenshot() (返回二进制图像数据)
• 运行命令：output = desktop.commands.run("ls -la")
• 文件操作：desktop.files.write("/path/to/file", "content")

提示：底层环境基于 Linux 和 Xfce 桌面系统，您可以根据需要自定义沙箱模板以预装特定依赖。