sprites

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sprites

A sprite is a persistent, hardware-isolated Linux environment. It keeps its filesystem between sessions, gets a public hostname, runs services that survive disconnects, and can be snapshotted and restored in seconds.

Before anything else, work out where you are running. Every operation has two forms, and picking the wrong one wastes a turn.

Sprite是一种持久化、硬件隔离的Linux环境。它会在会话之间保留文件系统，拥有公共主机名，可运行断开连接后仍能存活的服务，并且能在数秒内完成快照和恢复。

首先，请确定你当前的运行环境。 每个操作都有两种执行形式，选错形式会浪费操作步骤。

Step 1: detect the context

步骤1：检测运行上下文

bash

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

Result	Meaning	Control plane to use
`inside`	The agent is running in the sprite	`sprite-env` CLI at `/.sprite/bin/sprite-env`
`outside`	The agent is on a laptop, CI runner, or another host	`sprite` CLI, the Sprites MCP server, or the REST API

Cache the answer for the session; it cannot change mid-session.

The two control planes are not interchangeable:

```
sprite-env
```
talks to the local API socket. It always acts on this sprite and takes no sprite name. It cannot see or touch other sprites.
```
sprite
```
talks to
```
https://api.sprites.dev
```
over the network. Nearly every command needs a target sprite (
```
-s <name>
```
), and it can create and destroy sprites.

Do not call

sprite-env

from outside a sprite, and do not use the remote MCP tools or

sprite -s <self>

from inside a sprite to manage the sprite you are already in. See environment detection for the fallbacks when neither binary is installed.

bash

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。当未安装任一二进制文件时的降级方案，请查看环境检测。

Step 2: pick the smallest operation

步骤2：选择最小化操作

Goal	Inside a sprite	Outside a sprite	Reference
Identify the environment	`sprite-env info`	`sprite list` , `sprite url -s <name>`	environment-detection.md
Run a command	Run it directly in the shell	`sprite exec -s <name> -- <cmd>`	remote.md
Keep a process alive	`sprite-env services create ...`	`sprite exec -s <name> -- sprite-env services create ...`	services.md
Expose a preview URL	`--http-port` on the service	same, plus `sprite url`	services.md
Snapshot / roll back state	`sprite-env checkpoints create`	`sprite checkpoint create -s <name>`	checkpoints.md
Move files in or out	Ordinary file tools, or `git clone`	`sprite file push` / `sprite file pull`	files.md
Allow or deny outbound domains	read-only from inside	`sprite api .../policy/network`	network-policy.md
Reach a third-party API	Gateway at `api.sprites.dev/v1/gateway`	Run the gateway call inside the sprite	api-gateway.md
Create or delete an environment	Not possible	`sprite create` / `sprite destroy`	remote.md

目标	在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

Golden path

标准操作流程

Detect inside or outside. Choose the control plane once.
Identify the exact sprite by name. From outside, get it from
```
sprite list
```
or from
```
.sprite/config
```
(
```
sprite use
```
); never guess a name.
Inspect before you mutate. Read service state, logs, or checkpoint lists first.
Checkpoint valuable state before risky work. Checkpoints take seconds.
Do the work:
```
exec
```
for bounded commands, a service for anything that must outlive the call.
Verify with real output — exit status, service state, logs, an HTTP probe.
Report the sprite name, the URL and its auth mode, and any checkpoint IDs.

检测是在sprite内部还是外部。一次性选定控制平面。
通过名称确定具体的sprite。在外部环境中，可从
```
sprite list
```
或
```
.sprite/config
```
（使用
```
sprite use
```
）获取名称；切勿猜测名称。
在修改前先检查状态。先查看服务状态、日志或检查点列表。
在执行高风险操作前，先为重要状态创建检查点。创建检查点仅需数秒。
执行操作：使用
```
exec
```
执行有限时长的命令，使用服务执行任何需要在调用结束后仍持续运行的任务。
通过实际输出验证结果——退出状态、服务状态、日志、HTTP探测。
报告sprite名称、URL及其认证模式，以及所有检查点ID。

Safety rules

安全规则

A sprite URL may be public. Never serve environment variables, tokens, key files, unfiltered logs, or admin endpoints from a sprite service.
```
checkpoint restore
```
rewinds the filesystem and discards later changes. Explain that and get approval before running it.
```
destroy
```
is irreversible and takes the services, checkpoints, and URL with it. Require explicit intent.
Network policy updates replace the whole rule set. Read the current policy, merge, then write.

Full detail in safety.

Sprite的URL可能是公开的。切勿从sprite服务中提供环境变量、令牌、密钥文件、未过滤日志或管理端点。
```
checkpoint restore
```
会回滚文件系统并丢弃后续更改。执行前需向用户说明这一点并获得批准。
```
destroy
```
操作不可逆转，会同时删除服务、检查点和URL。需用户明确确认意图。
网络策略更新会替换整个规则集。请先读取当前策略，合并修改后再写入。

详细内容请查看safety。

References

参考文档

Read the one that matches the task; each is self-contained.

environment-detection.md — deciding inside vs outside, installing either CLI, and auth setup.
remote.md — driving sprites from outside: create, list, exec, sessions, files, ports, destroy.
services.md — long-running processes, the service manager, and the public HTTP URL.
checkpoints.md — snapshots, rollback, and reading old files from mounted checkpoints.
network-policy.md — outbound egress rules and the read-modify-write update procedure.
api-gateway.md — third-party APIs (GitHub, Slack, …) with credentials injected by the gateway.
cli.md — the full
```
sprite-env
```
and
```
sprite
```
command surface.
http-api.md — REST endpoints behind both CLIs, for agents with only an HTTP client.
files.md — moving code and data in and out.
safety.md — confirmation rules and exposure limits.

请阅读与任务匹配的文档；每个文档都是独立完整的。

environment-detection.md — 确定内部/外部环境、安装任一CLI以及认证设置。
remote.md — 从外部管理sprite：创建、列出、执行命令、会话、文件、端口、销毁。
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 — 确认规则和暴露限制。