一、适用场景
·将本地代码文件或配置上传到沙箱 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 执行任意命令。