概述

沙箱持久化功能(目前为公开测试版)允许您暂停沙箱并稍后恢复,同时保持完整的状态——包括文件系统和内存——供后续访问。

状态转换

沙箱在其生命周期中会经历以下状态:

状态转换:

                  betaPause()
    ┌─────────────────────────────────┐
    │                                 ▼
┌───────────┐                   ┌───────────┐
  Running                          Paused
   运行中                            已暂停
└───────────┘                   └───────────┘
    │   ▲                             │
    │   └─────────────────────────────┘
    │           connect()             │
    │                                 │
    │ kill()                    kill()│
    ▼                                 ▼
┌─────────────────────────────────────────┐
                Killed 已终止
└─────────────────────────────────────────┘

暂停沙箱

使用 betaPause() 方法暂停沙箱。暂停操作会保存文件系统和内存,包括”所有运行中的进程、已加载的变量、数据等”。您可以存储沙箱 ID 以便稍后恢复。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandbox = await Sandbox.create()

  // Do some work
  await sandbox.commands.run('echo "Hello World" > /tmp/file.txt')

  // Pause the sandbox
  await sandbox.betaPause()

  // Save the sandbox ID for later
  const sandboxId = sandbox.sandboxId
  console.log('Sandbox ID:', sandboxId)
}

main()

恢复沙箱

通过 connect() 方法使用沙箱 ID 恢复暂停的沙箱,该方法会自动恢复已暂停的实例,将沙箱恢复到之前的确切状态。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandboxId = 'your-sandbox-id' // 使用暂停时保存的 ID

  // Connect to the paused sandbox
  const sandbox = await Sandbox.connect(sandboxId)

  // Verify the state is restored
  const result = await sandbox.commands.run('cat /tmp/file.txt')
  console.log(result.stdout) // Output: Hello World

  await sandbox.kill()
}

main()

列出暂停的沙箱

使用 Sandbox.list() 方法可以查询暂停的沙箱,使用状态过滤器。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // List all paused sandboxes
  const paginator = await Sandbox.list({
    query: { state: ['paused'] }
  })
  const pausedSandboxes = await paginator.nextItems()

  console.log('Paused sandboxes:', pausedSandboxes)
}

main()

移除暂停的沙箱

使用 kill() 方法永久移除暂停的沙箱。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandboxId = 'your-sandbox-id'

  // Method 1: kill with sandbox object
  const sandbox = await Sandbox.connect(sandboxId)
  await sandbox.kill()

  // Method 2: kill by ID
  await Sandbox.kill(sandboxId)
}

main()

自动暂停(Beta)

沙箱可以通过 betaCreate()/beta_create() 配置自动暂停功能,在不活动后自动暂停(默认 10 分钟)。这会在保留状态的同时停止计算消耗。该功能在恢复后会持续有效。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const sandbox = await Sandbox.betaCreate({
    autoPause: {
      enabled: true,
      timeout: 600_000 // 10 minutes in milliseconds
    }
  })

  // Do some work
  await sandbox.commands.run('echo "Hello World"')

  // The sandbox will automatically pause after 10 minutes of inactivity
  // You can later reconnect to it using connect()
}

main()

网络连接注意事项

暂停时,所有网络服务将变得不可访问。恢复沙箱后,客户端需要重新建立连接。