> ## 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.

# 沙箱列表

> 了解 PPIO Agent 沙箱列表功能的归档使用方法，查阅该版本通过程序查看沙箱资源的流程，为维护现有资源管理集成提供参考。

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

```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()
```

> [!NOTE]
>
> 当您拿到了正在运行的沙箱 ID 后，您可以 [连接到该沙箱](/docs/sandbox/archive/sandbox-connect)。

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

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

```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()
```

### 列出所有沙箱

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

```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()
```

### 按条件过滤沙箱

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

```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()
```

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

```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()
```

### 高级分页

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

```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()
```

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

```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()
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.