sprites-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are managing remote Sprite VMs from a local machine using the

sprite

CLI. This skill covers the local-side CLI for controlling Sprites externally. (Sprites also have built-in agent context at

/.sprite/docs/

for agents running inside the Sprite.)

Sprites are persistent, hardware-isolated Linux VMs on Fly.io with durable filesystems backed by object storage.

你可以通过

sprite

CLI从本地机器管理远程Sprite虚拟机。本技能涵盖用于外部控制Sprite的本地端CLI用法。（Sprite内部也内置了Agent上下文，路径为

/.sprite/docs/

，供运行在Sprite内部的Agent使用。）

Sprite是Fly.io上提供的持久化、硬件隔离的Linux虚拟机，其持久化文件系统底层由对象存储提供支持。

CLI Basics

CLI基础

The

sprite

CLI controls remote Sprites. The

-s

flag specifies which Sprite,

-o

specifies the org.

bash

undefined

sprite

CLI用于控制远程Sprite。

-s

参数指定要操作的Sprite名称，

-o

参数指定所属组织。

bash

undefined

List all sprites

列出所有Sprite

sprite list

Execute a command on a sprite (blocks until done)

在指定Sprite上执行命令（执行完成前会阻塞）

sprite exec -s <name> -- <command>

Open interactive shell

打开交互式shell

sprite console -s <name>

Activate a sprite for the current directory (creates .sprite file)

为当前目录激活指定Sprite（会生成.sprite文件）

sprite use <name>


When a `.sprite` file exists in the working directory, `-s` can be omitted.

sprite use <name>


如果工作目录下存在`.sprite`文件，可以省略`-s`参数。

Executing Commands

执行命令

sprite exec

is the primary tool for remote work. Stdout and stderr are returned to the local terminal.

bash

undefined

sprite exec

是远程操作的核心工具，标准输出和标准错误会返回至本地终端。

bash

undefined

Run a single command

执行单个命令

sprite exec -s mysprite -- ls -la /home/sprite

Run a multi-part command (quote or use --)

执行多段命令（加引号或者使用--分隔）

sprite exec -s mysprite -- bash -c "cd /project && npm test"

Pipe output locally

输出管道传输到本地

sprite exec -s mysprite -- cat /path/to/file > local-copy.txt


**Important:** Each `sprite exec` invocation is a separate session. Environment variables, working directory, and shell state do not persist between calls. For stateful work, use `bash -c "..."` to chain commands, or use `sprite console` for interactive sessions.

**Environment variables:** The `-env` flag passes env vars to the remote session, but multiple `-env` flags only apply the **last** one. Use comma-separated format for multiple vars:

```bash

sprite exec -s mysprite -- cat /path/to/file > local-copy.txt


**重要提示：** 每次调用`sprite exec`都是独立会话，环境变量、工作目录、shell状态不会在多次调用之间留存。如果需要有状态的操作，可以使用`bash -c "..."`串联命令，或是使用`sprite console`开启交互式会话。

**环境变量：** `-env`参数可以向远程会话传递环境变量，但多个`-env`参数只会生效**最后一个**。传递多个变量请使用逗号分隔的格式：

```bash

WRONG — only BAR is set

错误用法 — 只有BAR会生效

sprite exec -s mysprite -env "FOO=1" -env "BAR=2" -- env

RIGHT — both are set

正确用法 — 两个变量都会生效

sprite exec -s mysprite -env "FOO=1,BAR=2" -- env

undefined

sprite exec -s mysprite -env "FOO=1,BAR=2" -- env

undefined

File Transfer

文件传输

There is no dedicated file transfer command. Use

sprite exec

with

cat

for pulling files, or pipe content in:

bash

undefined

没有专门的文件传输命令，你可以搭配

sprite exec

和

cat

拉取文件，或是通过管道传入内容：

bash

undefined

Pull a file from a sprite

从Sprite拉取文件

sprite exec -s mysprite -- cat /path/on/sprite > local-file.txt

Pull a binary file

拉取二进制文件

sprite exec -s mysprite -- base64 /path/to/binary | base64 -d > local-file.bin

Push a file to a sprite (via stdin)

向Sprite推送文件（通过标准输入）

cat local-file.txt | sprite exec -s mysprite -- bash -c "cat > /path/on/sprite"

For heavier file work, use SSHFS via proxy

如果需要传输大量文件，可以通过代理使用SSHFS

sprite proxy 2222 # then sshfs sprite@localhost:/home/sprite /mnt/sprite -p 2222

undefined

sprite proxy 2222 # 之后执行 sshfs sprite@localhost:/home/sprite /mnt/sprite -p 2222

undefined

Checkpoints

检查点

Checkpoints capture the writable overlay of the Sprite's filesystem. They are fast (sub-second, copy-on-write) and cheap.

bash

undefined

检查点会捕获Sprite文件系统的可写覆盖层，创建速度很快（亚秒级，写时复制实现）且成本极低。

bash

undefined

Create a checkpoint (with optional comment)

创建检查点（可添加可选备注）

sprite checkpoint create -s mysprite sprite checkpoint create -s mysprite -m "before risky refactor"

List checkpoints

列出所有检查点

sprite checkpoint list -s mysprite

Restore to a checkpoint (destructive — drops current session and all changes since)

恢复到指定检查点（破坏性操作 — 会丢弃当前会话和之后的所有变更）

sprite restore <checkpoint-id> -s mysprite


**Checkpoint aggressively.** Before any risky operation, before switching contexts, whenever something is working. Checkpoints are nearly free.

The last 5 checkpoints are also mounted inside the Sprite at `/.sprite/checkpoints/` for direct file-level inspection without restoring.

sprite restore <checkpoint-id> -s mysprite


**建议高频创建检查点：** 在任何高风险操作前、切换上下文前、或是功能正常运行时都可以创建，检查点几乎没有额外成本。

最近5个检查点也会挂载在Sprite内部的`/.sprite/checkpoints/`路径下，无需恢复即可直接在文件级别查看内容。

Networking

网络配置

Each Sprite gets a public HTTPS URL at

https://<name>-<org>.sprites.dev/

, routing to port 8080 by default.

bash

undefined

每个Sprite都有一个公共HTTPS地址：

https://<name>-<org>.sprites.dev/

，默认路由到8080端口。

bash

undefined

Show the sprite's URL and auth mode

查看Sprite的访问地址和认证模式

sprite url -s mysprite

Make the URL public (no auth required)

将地址设为公开访问（无需认证）

sprite url update --auth public -s mysprite

Restore authenticated mode

恢复为默认认证模式

sprite url update --auth default -s mysprite

Forward remote ports to local machine

将远程端口转发到本地机器

sprite proxy 8080 3000 -s mysprite


Network egress policy is managed via the Sprites REST API, not the CLI:

```bash

sprite proxy 8080 3000 -s mysprite


网络出口策略通过Sprites REST API管理，不支持CLI操作：

```bash

View current network policy (from inside the sprite)

查看当前网络策略（从Sprite内部执行）

sprite exec -s mysprite -- cat /.sprite/policy/network.json

Update network policy (from outside, via API)

更新网络策略（从外部通过API执行）

sprite api -s mysprite POST /policy/network
-d '{"rules": [{"include": "defaults"}, {"domain": "custom-api.com", "action": "allow"}]}'


Network policy can only be modified externally. The Sprite cannot change its own policy.

sprite api -s mysprite POST /policy/network
-d '{"rules": [{"include": "defaults"}, {"domain": "custom-api.com", "action": "allow"}]}'


网络策略仅支持从外部修改，Sprite本身无法修改自身的策略。

Services

服务管理

Services are long-running processes inside a Sprite that persist across reboots and hibernation.

bash

undefined

服务是Sprite内部的长运行进程，在重启和休眠后仍会保留。

bash

undefined

List services

列出所有服务

sprite exec -s mysprite -- sprite-env services list

Create a service

创建服务

sprite exec -s mysprite -- sprite-env services create <name> --cmd <binary> --args "<args>"

Get service status

查看服务状态

sprite exec -s mysprite -- sprite-env services get <name>

View service logs

查看服务日志

sprite exec -s mysprite -- cat /.sprite/logs/services/<name>.stderr.log


One service can be designated as the HTTP service (receives proxied requests on the Sprite's URL).

sprite exec -s mysprite -- cat /.sprite/logs/services/<name>.stderr.log


可以指定一个服务作为HTTP服务，接收Sprite公共地址转发的请求。

Multi-Sprite Coordination

多Sprite协同

When working across multiple Sprites, use

sprite list

to see the fleet, then target each by name:

bash

undefined

当需要操作多个Sprite时，可以先使用

sprite list

查看所有实例，再通过名称分别操作：

bash

undefined

Run the same command across all sprites

在所有Sprite上执行相同命令

for s in $(sprite list); do echo "=== $s ===" sprite exec -s "$s" -- <command> done


Each Sprite is fully isolated — no shared mutable state. Coordinate through explicit communication: files in shared Tigris buckets, HTTP endpoints, or Git repos.

for s in $(sprite list); do echo "=== $s ===" sprite exec -s "$s" -- <command> done


每个Sprite都是完全隔离的，没有共享的可变状态，需要通过显式通信完成协同：比如共享Tigris存储桶中的文件、HTTP接口或是Git仓库。

Lifecycle

生命周期管理

bash

undefined

bash

undefined

Create a new sprite

创建新的Sprite

sprite create <name> sprite create -o <org> <name>

Destroy a sprite (irreversible)

销毁Sprite（操作不可逆）

sprite destroy <name>


Sprites auto-sleep when idle (no active commands, TCP connections, TTY sessions, or running Services). They wake automatically on the next `sprite exec`, `sprite console`, or HTTP request to their URL. Anything on disk persists across sleep cycles. Running processes do not — use Services for daemons.

sprite destroy <name>


Sprite在空闲时会自动休眠（无活跃命令、TCP连接、TTY会话或运行中的服务），下次调用`sprite exec`、`sprite console`或是访问其HTTP地址时会自动唤醒。磁盘上的所有内容会在休眠周期中保留，运行中的进程不会保留 — 如果需要守护进程请使用服务。

Internal Sprite Paths

Sprite内部路径

When running commands on a Sprite, these paths are useful:

```
/.sprite/api.sock
```
— internal API Unix socket
```
/.sprite/policy/network.json
```
— read-only network policy
```
/.sprite/checkpoints/
```
— last 5 checkpoints mounted for inspection
```
/.sprite/logs/services/
```
— service logs
```
/.sprite/docs/
```
— platform documentation (agent-context.md, languages.md, docker.md)
```
/home/sprite/
```
— user home directory

在Sprite上执行命令时，以下路径非常有用：

```
/.sprite/api.sock
```
— 内部API Unix套接字
```
/.sprite/policy/network.json
```
— 只读网络策略
```
/.sprite/checkpoints/
```
— 最近5个检查点的挂载路径，可直接查看
```
/.sprite/logs/services/
```
— 服务日志路径
```
/.sprite/docs/
```
— 平台文档（包含agent-context.md、languages.md、docker.md）
```
/home/sprite/
```
— 用户家目录