文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>Agent Runtime>操作指南>沙箱内操作>文件系统

文件系统

最近更新时间：2026-06-03 09:09:00

我的收藏

本页目录：

Agent Sandbox 支持通过 CLI 和 HTTP 接口在沙箱 Instance 与本地之间传输文件。文件操作包括上传和下载单个文件。

适用场景

将本地代码文件或配置上传到沙箱 Instance 中执行。
将沙箱中生成的运行结果、日志或产物下载到本地。
通过管道（stdin/stdout）与自动化脚本集成文件传输。

前提条件

已创建可访问的沙箱 Instance，并获取 instance-id。参考实例生命周期确认 Instance 处于 RUNNING 状态。
已安装 agr CLI 并完成认证配置。运行以下命令确认 CLI 可用：
agr version
如需直接调用数据面 HTTP 接口，已获取对应 Instance 的访问地址和令牌。

使用 CLI 上传文件

将本地文件上传到沙箱指定路径：
agr instance file upload <instance-id> <local-path> <remote-path> -o json
参数说明：
参数
必填
说明
instance-id
是
目标沙箱 Instance ID
local-path
是
本地文件路径，使用 - 表示从 stdin 读取
remote-path
是
沙箱内目标文件路径
--user
否
指定沙箱内文件操作的用户身份
上传本地文件到沙箱示例如下：
agr instance file upload asdas-sdasd-sdad-abcdef12 ./config.yaml /home/user/config.yaml -o json
Expected output：
{
  "SchemaVersion": "agr.v1",
  "Command": "instance.file.upload",
  "Status": "succeeded",
  "Data": {
    "Operation": "upload",
    "Path": "/home/user/config.yaml",
    "LocalPath": "./config.yaml",
    "Size": 2048
  },
  "Failure": null,
  "Warnings": [],
  "Meta": {
    "Backend": "cloud",
    "DurationMs": 350
  }
}
Data.Path 为文件在沙箱中的实际写入路径，Data.Size 为上传的字节数。
通过管道从 stdin 上传示例如下：
echo "hello sandbox" | agr instance file upload asdas-sdasd-sdad-abcdef12 - /tmp/hello.txt -o json

使用 CLI 下载文件

将沙箱内文件下载到本地：
agr instance file download <instance-id> <remote-path> <local-path> -o json
参数说明：
参数
必填
说明
instance-id
是
目标沙箱 Instance ID
remote-path
是
沙箱内源文件路径
local-path
是
本地目标路径，使用 - 表示输出到 stdout
--user
否
指定沙箱内文件操作的用户身份
示例：
agr instance file download asdas-sdasd-sdad-abcdef12 /home/user/result.json ./result.json -o json
Expected output：
{
  "SchemaVersion": "agr.v1",
  "Command": "instance.file.download",
  "Status": "succeeded",
  "Data": {
    "Operation": "download",
    "Path": "/home/user/result.json",
    "LocalPath": "./result.json",
    "Size": 4096
  },
  "Failure": null,
  "Warnings": [],
  "Meta": {
    "Backend": "cloud",
    "DurationMs": 280
  }
}
Data.Size 为下载文件的字节数。
注意：
使用 -o json 时不能将 local-path 设为 -（stdout），两者会产生输出冲突。需要将文件内容输出到 stdout 时，去掉 -o json 参数。

通过 E2B 兼容接口操作文件

Agent Sandbox 数据面提供 E2B 兼容的 HTTP 接口，适用于需要直接集成 HTTP 调用的场景。

上传文件

curl -X POST "https://{instance-id}.{domain}/files?username=user&path=/home/user/config.yaml" \\
  -H "X-Access-Token: {token}" \\
  -H "Content-Type: application/octet-stream" \\
  --data-binary @./config.yaml

下载文件

curl -X GET "https://{instance-id}.{domain}/files?username=user&path=/home/user/result.json" \\
  -H "X-Access-Token: {token}" \\
  -o ./result.json

已知限制

agr instance file 提供 upload 和 download 两个子命令。列目录和目录监听不在当前 CLI 命令范围内。如需查看沙箱内的目录结构，可通过 agr instance exec 执行 shell 命令：
agr instance exec asdas-sdasd-sdad-abcdef12 -o json -- ls -la /home/user/
上传和下载操作为单文件传输，不支持目录递归。如需传输多个文件，逐个执行或使用归档格式（如 tar）打包后传输。
传输大文件时建议检查沙箱磁盘可用空间。
通过 stdin/stdout（-）传输时适合与管道和自动化脚本配合使用。
使用 --user 指定文件归属用户，确保沙箱内进程有权访问上传的文件。

清理资源

试用完成后，如不再需要沙箱 Instance，删除以释放资源：
agr instance delete <instance-id> -o json
示例：
agr instance delete asdas-sdasd-sdad-abcdef12 -o json
如果 Instance 不存在（已被删除），添加 --ignore-not-found 避免报错：
agr instance delete asdas-sdasd-sdad-abcdef12 --ignore-not-found -o json

相关文档

实例生命周期：确认 Instance 状态和可用性。
代码执行：在沙箱内运行脚本和程序。
Shell 与进程管理：通过 agr instance exec 执行任意命令。

中国站