如何用 OpenSandbox 主机卷挂载把宿主机目录安全共享给沙箱【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox如果你的沙箱任务需要读写宿主机上的数据集、模型文件或配置目录OpenSandbox 的 Volume API 提供了一条路径创建沙箱时传入host类型的Volume把宿主机目录绑定挂载进沙箱容器实现双向文件共享也可以只读共享或只挂子目录。整个过程的安全边界由服务端配置控制只有落在allowed_host_paths允许前缀下的宿主机路径才能被挂载。这篇文章给出一条完整可执行的主路径用 Docker 运行时启动 OpenSandbox Server、配置宿主机路径允许清单、用仓库自带的 examples/host-volume-mount/main.py 跑通读写、只读、SubPath 三种挂载模式并说明服务端对挂载请求的具体校验规则方便你排查挂载被拒绝的问题。准备条件启动 Server 并设置宿主机路径允许清单主路径的适用前提来自示例文档OpenSandbox Server 以Docker 运行时运行SDK 从源码安装Volume 支持尚未包含在已发布的 SDK 包中。1. 启动 OpenSandbox Server在项目的server/目录下执行cp opensandbox_server/examples/example.config.toml ~/.sandbox.toml uv sync uv run python -m opensandbox_server.main服务端默认读取~/.sandbox.toml也可以用环境变量SANDBOX_CONFIG_PATH指定其他配置文件路径见 server/configuration.md。示例配置默认监听 8080 端口运行时为[runtime] type docker见 示例配置。2. 配置allowed_host_paths允许清单在~/.sandbox.toml的[storage]段中设置允许挂载的宿主机路径前缀[storage] # Allowlist of host path prefixes permitted for bind mounts. # Only paths under these prefixes can be mounted into sandboxes. allowed_host_paths [/tmp/opensandbox-data, /data/shared]这是整个方案的核心安全项创建沙箱时只有位于这些前缀之下的宿主机路径才被接受。文档的安全提示是生产环境中必须显式设置allowed_host_paths防止沙箱访问敏感宿主机目录。这里有一处文档间的冲突需要注意docs/examples/host-volume-mount.md 中的注释说“为空则允许所有宿主机路径”而 server/configuration.md 的[storage]章节和权威 schema config.py 中的描述是“为空则拒绝所有 host 挂载secure-by-default”且configuration.md明确声明config.py为最高优先级的依据。因此主路径以“必须显式配置非空允许清单”为准——示例配置本身就是这样做的照抄示例不会踩到这个冲突。3. 创建宿主机目录与示例数据# Create a directory to share with sandboxes mkdir -p /tmp/opensandbox-data echo hello-from-host /tmp/opensandbox-data/marker.txt # Create a subdirectory for the subpath demo mkdir -p /tmp/opensandbox-data/datasets/train echo -e id,value\n1,100\n2,200\n3,300 /tmp/opensandbox-data/datasets/train/data.csv4. 从源码安装 SDK 并拉取沙箱镜像# From the project root (recommended: use uv) uv pip install -e sdks/sandbox/python也可以先在虚拟环境中用pip install -e sdks/sandbox/python。这一步不能省示例脚本启动时会检查Volume/Host模型是否存在缺失时会打印错误并直接退出。然后拉取沙箱要使用的镜像docker pull ubuntu:latest执行步骤运行示例并验证三种挂载模式在项目根目录运行示例脚本通过HOST_VOLUME_PATH指定要共享的宿主机目录HOST_VOLUME_PATH/tmp/opensandbox-data uv run python examples/host-volume-mount/main.py脚本还读取以下环境变量SANDBOX_DOMAIN默认localhost:8080、SANDBOX_API_KEY服务端启用 API key 认证时必须提供、SANDBOX_IMAGE默认ubuntu。如果不设置HOST_VOLUME_PATH脚本会自行创建一个临时目录并写入marker.txt用于快速演示。脚本依次执行三个场景每个场景都会创建沙箱、在沙箱内执行命令、最后kill沙箱读写挂载把宿主机目录挂到沙箱内/mnt/sharedreadOnlyFalse。验证链路是在沙箱内ls -la /mnt/shared/看到宿主机文件 → 在沙箱内写入sandbox-greeting.txt→cat读回 → 脚本再在宿主机侧检查该文件是否已出现出现则打印[4] Verified on host: ...及内容。如果宿主机侧看不到脚本会打印 “not directly visible (expected on remote Docker)”说明服务端与 Docker 不在同一台机器上。只读挂载同一目录挂到/mnt/readonlyreadOnlyTrue。验证读操作正常然后执行touch /mnt/readonly/should-fail.txt 21 || echo Write denied (expected)——写入会被容器运行时拒绝这是预期的成功表现。SubPath 挂载只挂载宿主机路径下的datasets/train子目录到/mnt/training-datareadOnlyTruesubPathdatasets/train。脚本会先在宿主机侧确保该子目录和data.csv存在然后在沙箱内ls和cat data.csv验证只暴露了子目录内容。全部完成后输出以下为文档中的示例结果 All scenarios completed successfully! 判断标准三个场景分别完成“宿主机文件在沙箱内可见且沙箱写入能在宿主机回读”“只读挂载下写入被拒绝”“SubPath 只暴露指定子目录”且最终打印All scenarios completed successfully!。可选分支在自己的代码里声明 host 卷如果你不需要跑完整示例而是在自己的 Python 代码中挂载docs/examples/host-volume-mount.md 给出的 SDK 用法async是from opensandbox import Sandbox from opensandbox.models.sandboxes import Host, Volume sandbox await Sandbox.create( imageubuntu, volumes[ Volume( namemy-data, hostHost(path/data/shared), mountPath/mnt/data, readOnlyFalse, # optional, default is False subPathsubdir, # optional, mount a subdirectory ), ], )其中host.path是宿主机上的绝对路径必须位于allowed_host_paths前缀之下mountPath是沙箱容器内的挂载点subPath是相对于host.path的子目录。文档同时提供了 sync Python、JavaScript/TypeScript、Java/Kotlin 版本。挂载被拒绝时服务端的校验规则创建请求中携带volumes时Docker 运行时会在建容器前做校验实现见 docker/volumes.py 与 validators.py。对照这些规则可以快速定位问题现象错误码触发条件HOST_PATH_NOT_ALLOWED400宿主机路径不在任何allowed_host_paths前缀之下。报错信息会列出当前允许的前缀列表把它加进[storage].allowed_host_paths后重试INVALID_HOST_PATH400路径不是绝对路径必须以/或 Windows 盘符如C:\开头、含..路径穿越组件、或未规范化双斜杠、除根目录外带尾斜杠INVALID_SUB_PATH400subPath是绝对路径、含..或解析后的路径逃出宿主机路径/允许前缀HOST_PATH_CREATE_FAILED500服务端无法在宿主机上创建挂载目录几条值得知道的边界行为子目录会自动创建对host卷若解析后的宿主机目录不存在服务端会先创建它再挂载已存在的普通文件则按文件挂载。符号链接也会被拦允许清单校验做了 realpath 解析白名单目录内指向外部的符号链接如link - /无法借此逃逸出允许前缀。只读模式readOnlyTrue对应 Docker bind 的:ro否则默认:rw只读拦截由容器运行时在写入时执行而不是创建时就拒绝。限制与后续参考Volume 功能要求从源码安装的最新 SDK已发布包中暂不包含脚本会在模型缺失时给出明确提示。本示例面向 Docker 运行时Kubernetes 运行时的 volume 模型host、pvc、ossfs在 API 层有各自的支持面配置差异见 server/configuration.md。设计背景可继续阅读OSEP-0003: Volume and VolumeBinding Support、OpenAPI 卷定义 specs/sandbox-lifecycle.yml、以及完整示例文档 docs/examples/host-volume-mount.md。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考