---
title: "Sine Box：文件、命令与运行环境"
description: "选择 Lite 或 Sandbox，创建 Box、管理文件并执行命令。了解 VM 运行窗口、备份、API 权限和执行费用。"
image: "https://docs.sinecloud.dev/opengraph.png"
---

> 完整文档索引： https://docs.sinecloud.dev/zh-CN/llms.txt

# Sine Box：文件、命令与运行环境

Sine Box 提供独立文件与执行空间。它不要求先使用 Agents 或创建项目。产品工作空间与具体 Box 是两层对象：准备工作空间后，还要选择或创建承载文件和运行历史的具体资源。

## 选择 Lite 或 Sandbox

| 类型 | 运行方式 | 计费依据 |
| --- | --- | --- |
| Lite | 使用有界 shell 执行命令，无需启动 Sandbox VM 窗口。 | 命令墙钟时长。 |
| Sandbox | 显式启动 VM 运行窗口后，访问实时文件并执行命令。 | 已确认的 VM 窗口时长，包含空闲；窗口内命令不重复计执行费。 |

创建时确定运行环境类型。可用类型、功能和操作取决于当前环境的发布配置、组织权限和运行服务，基础 Free 权限不保证所有运行能力都已开放。

## 创建与选择资源

1. 登录 [Console](https://sinecloud.dev/zh-CN/dashboard)，选择组织并进入 **Box**。
2. 首次没有产品工作空间时，由所有者或管理员准备资源；项目可选，默认可以直接属于组织。
3. 点击 **创建 Box**，选择 Lite 或 Sandbox 并完成表单。
4. 从 Box 选择器选中具体资源，再进入文件、命令或设置页面。

产品工作空间 ID 与具体 `boxId` 不同。使用创建结果的下一步链接可保留所选资源。浏览页面和切换 Box 不会自动启动 VM。

## 使用 Sandbox 运行窗口

1. 核对启动前显示的价格、可用余额和预留估算。
2. 显式启动运行窗口，默认十分钟，总运行窗口最多三十分钟。
3. 窗口有效时访问实时文件或执行命令。需要延长时使用续租，系统先按原窗口价格追加预留。
4. 无需继续运行时使用暂停，并检查状态是否得到确认。

预留估算不是锁价或执行承诺。暂停的 Sandbox 不会因读取文件或提交命令自动唤醒；命令也不会自动启动 VM。状态未知或查询失败时，先恢复原窗口状态，不要创建新的启动请求来替代它。

## 文件与命令

**文件**支持目录浏览、预览和下载。写入与删除需要 `fileWrite`；执行命令需要 `boxRun`，并满足当前价格、余额和运行配置要求。

在 **命令与执行** 中提交任务并查看选中 Box 的历史。命令使用 `executionId` 标识，Sandbox 窗口使用 `leaseId` 标识。响应丢失时查询原 `executionId` 或 `leaseId`，避免重复有副作用的命令。

历史摘要权限不等于完整输出权限。取消已派发命令需有运行端确认，未知状态不能视为已经停止或已经退款；关闭网页同样不会自动取消执行。

## 生命周期、备份与费用

在 **设置** 中管理选中资源的生命周期和持久备份；**概览**提供备份与历史窗口费用入口。销毁是独立操作，需要确认精确资源 ID。暂停资源权限与停止 VM 是不同状态，应分别核对。

从账务打开历史窗口只用于核对该窗口费用，不会自动恢复或启动当前窗口。需要操作当前运行窗口时，使用页面提供的明确入口。[组织用量与账务](/zh-CN/billing/)分别展示执行状态、占用预留和实际扣费。

## 与 Agents 或 API 配合

[Agents](/zh-CN/products/agents/) 可显式关联同组织、同项目范围的 Box；双方都直接属于组织时，项目范围相同。关联是可选的，不授予另一产品的权限。

程序接入使用 Box **API** 页提供的 `/api/box/v1/{boxId}` 地址，并创建带 Box 授权及所需功能的 [API 密钥](/zh-CN/api-keys/)。仅有 Agents 授权的密钥不能直接访问 Box。

来源: https://docs.sinecloud.dev/zh-CN/products/box/index.mdx