本节介绍如何通过各种方式查看您创建过的沙箱信息。 
import { Sandbox } from 'ppio-sandbox/code-interpreter'

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

// 列出所有正在运行的沙箱。
const runningSandboxesPaginator = await Sandbox.list({
  query: {
    state: ["running"],
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
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

await sandbox.kill()
当您拿到了正在运行的沙箱 ID 后，您可以 连接到该沙箱。

​
根据元数据过滤沙箱

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

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

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

const runningSandboxes = await runningSandboxesPaginator.nextItems()
for (const runningSandbox of runningSandboxes) {
  console.log(`list running sandbox (${runningSandbox.sandboxId}) metadata:`, runningSandbox.metadata)
}

await sandbox.kill()

​
列出所有沙箱

现已支持分页获取沙箱列表，详情参考 高级分页 部分。 
import { Sandbox, SandboxInfo } from 'ppio-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

const firstPage = await paginator.nextItems()
if (paginator.hasNext) {
    const nextPage = await paginator.nextItems()
}

await sandbox.kill()

​
按条件过滤沙箱

下面展示如何基于沙箱状态来过滤。状态参数可以是 running（正在运行的沙箱）、paused（已暂停的沙箱）或同时包含两者。 
import { Sandbox } from 'ppio-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

const sandboxes = await paginator.nextItems()

await sandbox.kill()
下面展示如何基于沙箱的元数据键值对来做过滤。 
import { Sandbox } from 'ppio-sandbox/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()

await sandbox.kill()

​
高级分页

您可以设置每页返回的沙箱数量（默认值和最大值都是 1000），通过指定偏移参数（nextToken 或 next_token）来分页获取沙箱列表。 
import { Sandbox } from 'ppio-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

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

// 是否有下一页
console.log("paginator.hasNext: ", paginator.hasNext)

// 下一页的偏移参数
console.log("paginator.nextToken: ", paginator.nextToken)

await sandbox.kill()
您可以通过循环遍历分页器来获取所有沙箱信息。 
import { Sandbox, SandboxInfo} from 'ppio-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

const paginator = Sandbox.list()

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

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

for (const sandbox of sandboxes) {
  console.log(`list sandbox (${sandbox.sandboxId})`)
}

await sandbox.kill()