跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

E2B Desktop

Runs a full Linux desktop environment in an isolated E2B cloud sandbox with screenshot, mouse, and keyboard control. E2BDesktopSandbox extends E2BSandbox, so everything the base provider supports (command execution, background processes, file upload, pause/resume reconnection) works against the same desktop machine. For interface details, see WorkspaceSandbox interface.

Installation
Installation的直接链接

npm install @mastra/e2b-desktop

Set your E2B API key with the E2B_API_KEY environment variable or the apiKey option.

Usage
Usage的直接链接

Add an E2BDesktopSandbox to a workspace and assign it to an agent. Because the sandbox supports the computer capability, the workspace registers the mastra_workspace_computer_* tools alongside the shell and process tools:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { E2BDesktopSandbox } from '@mastra/e2b-desktop'

const workspace = new Workspace({
  sandbox: new E2BDesktopSandbox({
    resolution: [1280, 720],
  }),
})

const agent = new Agent({
  id: 'desktop-agent',
  name: 'Desktop Agent',
  instructions: 'You can control a Linux desktop and run shell commands.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate(
  'Take a screenshot, then create /tmp/hello.txt with the text "hello" and cat it.',
)

The agent can mix desktop actions (click, type, screenshot) with shell commands. Both surfaces operate on the same machine.

Direct desktop control
Direct desktop control的直接链接

Use the computer capability programmatically without an agent:

const sandbox = new E2BDesktopSandbox()
await sandbox.start()

await sandbox.computer.leftClick(100, 200)
await sandbox.computer.type('hello')
const { data } = await sandbox.computer.screenshot() // PNG bytes

const size = await sandbox.computer.getScreenSize()
console.log(size) // { width: 1024, height: 768 }

Live desktop view
Live desktop view的直接链接

streamUrl() starts an authenticated noVNC stream inside the sandbox and returns a viewer URL. Open it in a browser to watch the agent work:

const url = await sandbox.computer.streamUrl()
// https://6080-<sandbox-id>.e2b.app/vnc.html?...&password=<auth-key>

Desktop SDK escape hatch
Desktop SDK escape hatch的直接链接

Desktop-only APIs such as launch, open, window helpers, and custom stream control are available on the underlying @e2b/desktop sandbox:

await sandbox.desktop.launch('xfce4-terminal')
await sandbox.desktop.open('https://mastra.ai')

Constructor parameters
Constructor parameters的直接链接

Accepts all E2BSandbox options plus:

resolution?:

[number, number]
Desktop display resolution as [width, height] in pixels. Applies to newly created sandboxes only.

dpi?:

number
Desktop display DPI. Applies to newly created sandboxes only.

When no template is provided, the E2B-hosted desktop template is used instead of the base provider's mountable template.

Properties
Properties的直接链接

computer:

SandboxComputer
Computer-use capability: screenshot, mouse, keyboard, and stream URL. See SandboxComputer reference.

desktop:

Sandbox
The underlying @e2b/desktop SDK sandbox for desktop-only APIs. Throws if the sandbox has not started.

name:

string
Provider name ('E2BDesktopSandbox')

provider:

string
Provider identifier ('e2b-desktop')

Cloud storage mounting
Cloud storage mounting的直接链接

The default desktop template has no FUSE tooling, so cloud storage mounting requires a custom desktop template with s3fs or gcsfuse installed. Pass it with the template option.

On this page