> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙箱列表

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>在运行本文档中的示例代码前，请确保您已正确配置环境变量，详情请参考 <a href="/sandbox/get-start#配置环境变量">配置环境变量</a>。</Note>;
  }
};

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

<SandboxConfigHint />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

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

  # 列出所有正在运行的沙箱。
  running_sandboxes_paginator = Sandbox.list(
    query=SandboxQuery(
      state=[SandboxState.RUNNING],
    ),
  )

  running_sandboxes = running_sandboxes_paginator.next_items()

  running_sandbox = running_sandboxes[0]
  print('Running sandbox metadata:', running_sandbox.metadata)
  print('Running sandbox id:', running_sandbox.sandbox_id)
  print('Running sandbox started at:', running_sandbox.started_at)
  print('Running sandbox template id:', running_sandbox.template_id)

  # 输出结果：
  # Running sandbox metadata: { name: 'My Sandbox' }
  # Running sandbox id: i30sjldvvjx446kbkoofj-abf219fd
  # Running sandbox started at: 2025-06-22T15:09:28.822Z
  # Running sandbox template id: uhop43uji8fr7qkfbmsp

  sandbox.kill()
  ```
</CodeGroup>

<Note>
  当您拿到了正在运行的沙箱 ID 后，您可以 <Link href="/sandbox/sandbox-connect">连接到该沙箱</Link>。
</Note>

### 根据元数据过滤沙箱

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox, SandboxQuery

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

  # 列出所有正在运行的沙箱，其中 `user_id` 键的值为 `123` 且 `env` 键的值为 `dev`。
  paginator = Sandbox.list(
      query=SandboxQuery(
          metadata={
              "user_id": "123",
              "env": "dev",
          }
      ),
  )

  sandbox.kill()
  ```
</CodeGroup>

### 列出所有沙箱

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

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

  firstPage = paginator.next_items()
  if paginator.has_next:
      nextPage = paginator.next_items()

  sandbox.kill()
  ```
</CodeGroup>

### 按条件过滤沙箱

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

  sandbox = Sandbox.create()

  # 列出所有正在运行的或暂停的沙箱。
  paginator = Sandbox.list(
      query=SandboxQuery(
          state=[SandboxState.RUNNING, SandboxState.PAUSED],
      ),
  )

  # 获取第一页的沙箱（正在运行的和暂停的）
  sandboxes = paginator.next_items()

  sandbox.kill()
  ```
</CodeGroup>

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox, SandboxQuery

  sandbox = Sandbox.create(
      metadata={
          "env": "dev",
          "app": "my-app",
          "user_id": "123",
      },
  )

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

  sandboxes = paginator.next_items()

  sandbox.kill()
  ```
</CodeGroup>

### 高级分页

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  paginator = Sandbox.list(
      limit=1000,
      # next_token='<base64-encoded-token>',
  )

  # 获取下一页的沙箱
  paginator.next_items()

  # 是否有下一页
  print("paginator.has_next: ", paginator.has_next)

  # 下一页的偏移参数
  print("paginator.next_token: ", paginator.next_token)

  sandbox.kill()
  ```
</CodeGroup>

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  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()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox, SandboxInfo

  sandbox = Sandbox.create()

  paginator = Sandbox.list()

  # 循环遍历所有页面
  sandboxes: list[SandboxInfo] = []

  while paginator.has_next:
      items = paginator.next_items()
      sandboxes.extend(items)

  sandbox.kill()
  ```
</CodeGroup>