sprites

Sprites

Sprite 是一种持久化、硬件隔离的 Linux 环境。它会在会话之间保留文件系统，获得一个公共主机名，运行在断开连接后仍会继续运行的服务，并可在几秒内创建快照和恢复。

首先，确定你当前运行的位置。 每项操作都有两种形式，选错会浪费一次操作。

第 1 步：检测上下文

test -S /.sprite/api.sock && echo inside || echo outside

结果	含义	要使用的控制平面
inside	Agent 正在 Sprite 内部运行	/.sprite/bin/sprite-env 处的 sprite-env CLI
outside	Agent 正在笔记本电脑、CI 运行器或其他主机上运行	sprite CLI、Sprites MCP 服务或 REST API

在本次会话中缓存检测结果；会话期间不会改变。

两个控制平面不可互换：

• sprite-env 使用本地 API 套接字。它始终作用于当前 Sprite，且不需要 Sprite 名称。它无法查看或操作其他 Sprite。
• sprite 通过网络与 https://api.sprites.dev 通信。几乎每条命令都需要指定目标 Sprite（-s <name>），并且它可以创建和销毁 Sprite。

不要在 Sprite 外部调用 sprite-env，也不要在 Sprite 内部使用远程 MCP 工具或 sprite -s <self> 来管理当前所在的 Sprite。如果两种二进制文件都未安装，请参阅环境检测了解备用方案。

第 2 步：选择最精简的操作

目标	在 Sprite 内部	在 Sprite 外部	参考
识别环境	sprite-env info	sprite list、sprite url -s <name>	environment-detection.md
运行命令	直接在 shell 中运行	sprite exec -s <name> -- <cmd>	remote.md
保持进程运行	sprite-env services create ...	sprite exec -s <name> -- sprite-env services create ...	services.md
暴露预览 URL	在服务上使用 --http-port	同左，另加 sprite url	services.md
创建快照 / 回滚状态	sprite-env checkpoints create	sprite checkpoint create -s <name>	checkpoints.md
移入或移出文件	普通文件工具，或 git clone	sprite file push / sprite file pull	files.md
允许或拒绝访问出站域名	在内部只能读取	sprite api .../policy/network	network-policy.md
访问第三方 API	使用 api.sprites.dev/v1/gateway 处的网关	在 Sprite 内运行网关调用	api-gateway.md
创建或删除环境	无法执行	sprite create / sprite destroy	remote.md

推荐流程

1. 检测是在内部还是外部，并选择一个控制平面。
2. 根据名称确定准确的 Sprite。从外部操作时，从 sprite list 或 .sprite/config（sprite use）中获取名称；切勿猜测。
3. 修改之前先检查。先查看服务状态、日志或检查点列表。
4. 在进行高风险操作前，为重要状态创建检查点。创建检查点只需几秒。
5. 执行操作：对于有时限的命令，使用 exec；对于必须持续运行的任务，使用服务。
6. 根据实际输出进行验证，例如退出状态、服务状态、日志或 HTTP 探测。
7. 报告 Sprite 名称、URL 及其身份验证模式，以及任何检查点 ID。

安全规则

• Sprite URL 可能是公开的。切勿通过 Sprite 服务提供环境变量、令牌、密钥文件、未经筛选的日志或管理端点。
• checkpoint restore 会回退文件系统并丢弃之后的更改。运行前应说明这一点并获得批准。
• destroy 操作不可逆，并会一并删除服务、检查点和 URL。必须获得明确授权。
• 网络策略更新会替换整套规则。先读取当前策略，再合并，最后写入。

详情请参阅安全。

参考资料

阅读与任务匹配的文档；每份文档均为独立内容。

• environment-detection.md — 判断在内部还是外部操作、安装任一 CLI，以及设置身份验证。
• remote.md — 从外部控制 sprites：创建、列出、执行命令、管理会话和文件、端口，以及销毁。
• services.md — 长时间运行的进程、服务管理器，以及公共 HTTP URL。
• checkpoints.md — 快照、回滚，以及读取已挂载检查点中的旧文件。
• network-policy.md — 出站网络规则和读取-修改-写入更新流程。
• api-gateway.md — 第三方 API（GitHub、Slack 等），由网关注入凭据。
• cli.md — sprite-env 和 sprite 命令的完整功能。
• http-api.md — 两个 CLI 背后的 REST 端点，适用于只有 HTTP 客户端的 Agent。
• files.md — 在内外部传输代码和数据。
• safety.md — 确认规则和暴露限制。