跳到正文
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
浏览文档

接口

管理 CLI 参考

使用全部八项管理操作完成发现、生命周期管理、压缩和导出。

本页内容+

运行之前

sandbox-manager-cli 负责宿主机发现、生命周期、层栈压缩和导出。它使用系统范围，并把每个沙箱 ID 作为操作参数。

Shell
sandbox-manager-cli help
sandbox-manager-cli help create_sandbox

可将 --gateway-socket、--gateway-auth-token 和全局 --progress 参数放在操作之前或之后。建议使用 CLI 认证中说明的仓库令牌包装器，避免把令牌写入 shell 历史。

按类别筛选操作

显示 8 / 8 项命令。

宿主机发现

查找本地镜像和选择器可见的工作区根目录。

list_docker_images

列出本地 Docker 镜像引用

只读

列出所有本地 Docker 镜像引用，包括可用于创建沙箱的无标签镜像 ID。

何时使用

  1. 当调用方需要有效的本地镜像引用时，请在 create_sandbox 之前调用。
  2. 结果可能包含标签、摘要和无标签镜像 ID；请原样传入选中的字符串。
  3. 此操作不会拉取镜像，也不会创建沙箱。

语法

用法
sandbox-manager-cli list_docker_images

参数

无参数。

示例

Shell
sandbox-manager-cli list_docker_images

代表性结果

JSON 输出
{
  "images": [
    "ubuntu:24.04",
    "sha256:abc123…"
  ]
}

结果约定： images 是已配置运行时提供器返回的完整集合。

相关操作create_sandbox

list_workspace_directories

浏览允许使用的工作区目录

只读

省略 path 时列出选择器可见的工作区根目录；指定后最多列出所选目录的 500 个直接子目录。

何时使用

  1. 省略 path 先列出选择器可见的根目录，再逐层浏览返回的绝对路径。
  2. 每次只返回直接子目录；如需深入，请重复调用。
  3. 将选中的绝对路径作为 create_sandbox.workspace_root。

语法

用法
sandbox-manager-cli list_workspace_directories [--path PATH]

参数

参数类型必填说明
--path PATHstring否要浏览的、选择器可见的绝对工作区目录。省略时列出根目录。

示例

Shell
sandbox-manager-cli list_workspace_directories
sandbox-manager-cli list_workspace_directories --path /home/me/project

代表性结果

JSON 输出
{
  "path": "/host/workspaces",
  "parent": "/host",
  "truncated": false,
  "directories": [
    {
      "name": "example",
      "path": "/host/workspaces/example"
    }
  ]
}

结果约定： 位于已配置根目录时，path 和 parent 可能为 null；超过浏览上限后 truncated 为 true。

相关操作create_sandbox

沙箱生命周期

创建、枚举、检查和移除由管理器维护的记录。

create_sandbox

创建并启动一个或多个沙箱

修改状态

创建宿主机侧沙箱记录和运行时沙箱，然后启动其守护进程。

何时使用

  1. 先用发现操作选择有效的本地镜像和允许的工作区根目录。
  2. count=1 返回一条记录；更大的值返回 sandboxes 数组。
  3. 多沙箱批次创建失败时会回滚；成功创建会修改宿主机和容器状态。

语法

用法
sandbox-manager-cli create_sandbox --image IMAGE --workspace-bind-root PATH [--count N]

参数

参数类型必填说明
--image IMAGEstring是用于创建沙箱的容器镜像。
--workspace-bind-root PATHstring是绑定挂载到沙箱中的宿主机绝对工作区目录。
--count Ninteger否；默认值 1要创建的沙箱数量（最少为 1）。大于 1 时共享一个只读工作区基础层。

示例

Shell
sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root /testbed
sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root /testbed --count 5

代表性结果

JSON 输出
{
  "id": "sbox-example",
  "workspace_root": "/host/workspaces/example",
  "state": "ready",
  "daemon": {
    "host": "127.0.0.1",
    "port": 41001
  },
  "daemon_http": {
    "host": "127.0.0.1",
    "port": 42001
  },
  "shared_base": {
    "source": "/host/cache/shared-base/rootfs",
    "target": "/eos/layer-stack/shared-base",
    "root_hash": "sha256:…",
    "readonly": true
  }
}

结果约定： count 为 1 时返回一条记录；大于 1 时返回 { sandboxes: [record, …] }。

相关操作list_sandboxesinspect_sandboxdestroy_sandbox

list_sandboxes

列出管理器已知的沙箱

只读

列出管理器已知的沙箱记录，包括生命周期状态和已配置的守护进程端点元数据。

何时使用

  1. 将其作为 sandbox_id 和生命周期状态的主要只读来源。
  2. 记录处于创建、停止中、已停止或失败状态时，可能没有可用的守护进程元数据。
  3. 已保存的端点不代表一定可达；需要确认健康状态时请使用 observability snapshot。

语法

用法
sandbox-manager-cli list_sandboxes

参数

无参数。

示例

Shell
sandbox-manager-cli list_sandboxes

代表性结果

JSON 输出
{
  "sandboxes": [
    {
      "id": "sbox-example",
      "workspace_root": "/host/workspaces/example",
      "state": "ready",
      "daemon": {
        "host": "127.0.0.1",
        "port": 41001
      },
      "daemon_http": {
        "host": "127.0.0.1",
        "port": 42001
      },
      "shared_base": {
        "source": "/host/cache/shared-base/rootfs",
        "target": "/eos/layer-stack/shared-base",
        "root_hash": "sha256:…",
        "readonly": true
      }
    }
  ]
}

结果约定： 管理器没有记录时，sandboxes 为空。

相关操作inspect_sandboxcreate_sandbox

inspect_sandbox

检查一条沙箱记录

只读

检查沙箱记录，包括生命周期状态、工作区根目录和已配置的守护进程端点元数据。

何时使用

  1. 需要某条记录及其端点元数据时，请使用 list_sandboxes 返回的 ID。
  2. 此操作只读取管理器注册表，不会调用守护进程，也不能证明运行时健康。
  3. 请将工作区路径和端点视为运维元数据。

语法

用法
sandbox-manager-cli inspect_sandbox --sandbox-id ID

参数

参数类型必填说明
--sandbox-id IDstring是沙箱 ID。

示例

Shell
sandbox-manager-cli inspect_sandbox --sandbox-id sbox-1

代表性结果

JSON 输出
{
  "id": "sbox-example",
  "workspace_root": "/host/workspaces/example",
  "state": "ready",
  "daemon": {
    "host": "127.0.0.1",
    "port": 41001
  },
  "daemon_http": {
    "host": "127.0.0.1",
    "port": 42001
  },
  "shared_base": {
    "source": "/host/cache/shared-base/rootfs",
    "target": "/eos/layer-stack/shared-base",
    "root_hash": "sha256:…",
    "readonly": true
  }
}

结果约定： 在 ready 之外的生命周期状态中，daemon、daemon_http 和 shared_base 可能为 null。

相关操作list_sandboxessnapshot

destroy_sandbox

停止并移除沙箱

修改状态

停止沙箱守护进程、销毁运行时沙箱，并移除宿主机侧沙箱记录。

何时使用

  1. 调用前先用 inspect_sandbox 确认目标。
  2. 管理器会停止守护进程、销毁运行时、将记录标为 stopped，然后移除记录。
  3. 若销毁运行时失败，记录会以 failed 状态保留，供运维人员恢复。

语法

用法
sandbox-manager-cli destroy_sandbox --sandbox-id ID

参数

参数类型必填说明
--sandbox-id IDstring是沙箱 ID。

示例

Shell
sandbox-manager-cli destroy_sandbox --sandbox-id sbox-1

代表性结果

JSON 输出
{
  "id": "sbox-example",
  "workspace_root": "/host/workspaces/example",
  "state": "stopped",
  "daemon": {
    "host": "127.0.0.1",
    "port": 41001
  },
  "daemon_http": {
    "host": "127.0.0.1",
    "port": 42001
  },
  "shared_base": {
    "source": "/host/cache/shared-base/rootfs",
    "target": "/eos/layer-stack/shared-base",
    "root_hash": "sha256:…",
    "readonly": true
  }
}

结果约定： 成功时返回已移除记录的最终 stopped 状态。

相关操作list_sandboxesinspect_sandbox

层交付

压缩已发布层，或在宿主机上物化其增量。

squash_layerstacks

压缩符合条件的已发布层

修改状态

将每个可压缩区段合并为等价的扁平层，并把在线工作区会话迁移到更短的层链。

何时使用

  1. 用于运维人员主动执行存储压缩；此操作会改变活动层 manifest。
  2. 守护进程提交等价的扁平层，并报告迁移或租约处理结果。
  3. 不支持压缩操作的旧守护进程会返回 operation_failed，必须重新创建。

语法

用法
sandbox-manager-cli squash_layerstacks --sandbox-id ID

参数

参数类型必填说明
--sandbox-id IDstring是沙箱 ID。

示例

Shell
sandbox-manager-cli squash_layerstacks --sandbox-id sbox-1

代表性结果

JSON 输出
{
  "manifest_version": 5,
  "squashed_blocks": [
    {
      "squashed_layer_id": "layer-flat-5",
      "replaced_layer_ids": [
        "layer-2",
        "layer-3"
      ],
      "replaced_layers": "reclaimed"
    }
  ],
  "swept_sessions": [
    {
      "session_id": "workspace_17",
      "disposition": "migrated"
    }
  ]
}

结果约定： 可选的 blocked_reasons 和 faulty_sessions 用于说明未完全回收的原因。

相关操作inspect_sandboxexport_changeslayerstack

export_changes

应用或归档已发布增量

修改状态

把基础层之上的全部已发布层折叠为经过验证的增量，并应用到宿主机目录或写入归档。

何时使用

  1. 使用 dir 将增量应用到宿主机目录；使用 tar/tar-zst 原子写入归档。
  2. dest 必须是绝对路径；禁止使用文件系统根目录、家目录、管理器状态目录和导出暂存目录。
  3. 管理器会验证守护进程返回的字节，并且是唯一写入宿主机目标的组件。

语法

用法
sandbox-manager-cli export_changes --sandbox-id ID --dest PATH [--format dir|tar|tar-zst]

参数

参数类型必填说明
--sandbox-id IDstring是沙箱 ID。
--dest PATHstring是宿主机绝对目标路径：dir 使用目录，tar 格式使用归档文件。
--format dir|tar|tar-zststring否；默认值 dir输出格式：dir、tar 或 tar-zst。

示例

Shell
sandbox-manager-cli export_changes --sandbox-id sbox-1 --dest /home/me/myproject
sandbox-manager-cli export_changes --sandbox-id sbox-1 --dest /tmp/delta.tar.zst --format tar-zst

代表性结果

JSON 输出
{
  "manifest_version": 7,
  "format": "tar-zst",
  "layers_exported": [
    "layer-6",
    "layer-7"
  ],
  "files_written": 12,
  "symlinks_written": 1,
  "whiteouts_emitted": 2,
  "bytes_written": 48211
}

结果约定： dir 结果报告删除和不透明目录清除；归档结果报告输出的 whiteout。

相关操作inspect_sandboxsquash_layerstacks

输出、进度与退出码

操作成功时向 stdout 写入一份 JSON 响应。网关或操作错误向 stderr 写入 JSON 错误 envelope。--progress 会把网关日志流式写入 stderr，对 create_sandbox 最有帮助；最终响应仍写入 stdout。

退出码含义输出
0帮助或操作成功stdout 上的帮助文本或 JSON
1传输或远程操作失败stderr 上的错误 envelope
2语法、本地校验或配置失败stderr 上的错误 envelope

18 个结果