sprites-remote

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在其内部

/.sprite/docs/

路径下也为运行在Sprite内部的Agent提供了内置的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.

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


**重要提示：** 每次`sprite exec`调用都是一个独立的会话。环境变量、工作目录和Shell状态不会在多次调用之间保留。如需进行有状态的操作，可以使用`bash -c "..."`来链式执行命令，或者使用`sprite console`进入交互式会话。

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的URL和认证模式

sprite url -s mysprite

Make the URL public (no auth required)

设置URL为公开模式（无需认证）

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


网络出站策略通过Sprite 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 URL的代理请求）。

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

查看所有Sprite，然后通过名称指定目标：

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`或向其URL发送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/
```
—— 用户主目录