本节介绍如何通过各种方式查看您创建过的沙箱信息。

请注意，Beta 版 SDK 中 “获取沙箱列表” 的相关方法有重大更新，详情请参考 Beta 版 SDK 变动。

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

// 创建一个沙箱，并设置元数据。
const sandbox = await Sandbox.create({
  metadata: {
    name: 'My Sandbox',
  },
})

// 列出所有正在运行的沙箱。
const runningSandboxes = await Sandbox.list()
const runningSandbox = runningSandboxes[0]

console.log('Running sandbox metadata:', runningSandbox.metadata)
console.log('Running sandbox id:', runningSandbox.sandboxId)
console.log('Running sandbox started at:', runningSandbox.startedAt)
console.log('Running sandbox template id:', runningSandbox.templateId)

// 输出示例：
// Running sandbox metadata: { name: 'My Sandbox' }
// Running sandbox id: ili9gpg1fr0z407y1pyk8-1e67fa95
// Running sandbox started at: 2025-06-22T14:52:41.922Z
// Running sandbox template id: uhop43uji8fr7qkfbmsp

当您拿到了正在运行的沙箱 ID 后，您可以 连接到该沙箱。

​
根据元数据过滤沙箱

您可以通过指定 元数据 键值对来过滤沙箱。指定多个键值对将返回匹配所有条件的沙箱列表。如果您创建了大量沙箱，通过这种方式能帮助高效查找到特定沙箱。

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

// 创建一个沙箱，并设置元数据。
const sandbox = await Sandbox.create({
  metadata: {
    env: 'dev',
    app: 'my-app',
    userId: '123',
  },
})

// 列出所有正在运行的沙箱，其中 `userId` 键的值为 `123` 且 `env` 键的值为 `dev`。
const runningSandboxes = await Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

​
Beta 版 SDK 变动

当您正在使用 Beta 版本的 SDK 时，请参考如下方式来获取沙箱列表信息。

​
列出沙箱

现已支持分页获取沙箱列表，详情参考 高级分页 部分。

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

const sandbox = await Sandbox.create()

// 列出所有沙箱（包括正在运行的和暂停的）
const paginator = Sandbox.list()

const firstPage = await paginator.nextItems()
const nextPage = await paginator.nextItems()

​
按条件过滤沙箱

下面展示如何基于沙箱状态来过滤。状态参数可以是 running（正在运行的沙箱）、paused（已暂停的沙箱）或同时包含两者。

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

const sandbox = await Sandbox.create()

// 列出所有正在运行的或暂停的沙箱。
const paginator = Sandbox.list({
  query: {
    state: ['running', 'paused'],
  },
})

const sandboxes = await paginator.nextItems()

下面展示如何基于沙箱的元数据键值对来做过滤。

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

const sandbox = await Sandbox.create({
  metadata: {
    env: 'dev',
    app: 'my-app',
    userId: '123',
  },
})

// 列出所有正在运行的沙箱，其中元数据中的 `userId` 值为 `123` 且 `env` 值为 `dev`。
const paginator = Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

const sandboxes = await paginator.nextItems()

​
高级分页

您可以设置每页返回的沙箱数量（默认值和最大值都是 1000），通过指定偏移参数（nextToken 或 next_token）来分页获取沙箱列表。

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

const paginator = Sandbox.list({
  limit: 1000,
  nextToken: '<base64-encoded-token>',
})

// 是否有下一页
paginator.hasNext

// 下一页的偏移参数
paginator.nextToken

// 获取下一页的沙箱
await paginator.nextItems()

您可以通过循环遍历分页器来获取所有沙箱信息。

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

const paginator = Sandbox.list()

// 循环遍历所有页面
const sandboxes: SandboxInfo[] = []

while (paginator.hasNext) {
  const items = await paginator.nextItems()
  sandboxes.push(...items)
}