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

sprite

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

你可以通过

sprite

CLI从本地机器管理远程Sprite虚拟机。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 list

Execute a command on a sprite (blocks until done)

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

Open interactive shell

sprite console -s <name>

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

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 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)

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

For heavier file work, use SSHFS via proxy

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

undefined

sprite proxy 2222 # then 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 -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 exec -s mysprite -- cat /.sprite/policy/network.json

Update network policy (from outside, via 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，然后通过名称定位每个Sprite：

bash

undefined

Run the same command across all sprites

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 create <name> sprite create -o <org> <name>

Destroy a sprite (irreversible)

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请求时，会自动唤醒。磁盘上的所有内容会在休眠周期中保留，但运行中的进程不会——如需后台服务请使用Services。

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/
```
— 用户主目录

sprites

Original

Translation

CLI Basics

CLI基础

List all sprites

List all sprites

Execute a command on a sprite (blocks until done)

Execute a command on a sprite (blocks until done)

Open interactive shell

Open interactive shell

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

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

Executing Commands

执行命令

Run a single command

Run a single command

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

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

Pipe output locally

Pipe output locally

File Transfer

文件传输

Pull a file from a sprite

Pull a file from a sprite

Pull a binary file

Pull a binary file

Push a file to a sprite (via stdin)

Push a file to a sprite (via stdin)

For heavier file work, use SSHFS via proxy

For heavier file work, use SSHFS via proxy

Checkpoints

检查点

Create a checkpoint (with optional comment)

Create a checkpoint (with optional comment)

List checkpoints

List checkpoints

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

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

Networking

网络

Show the sprite's URL and auth mode

Show the sprite's URL and auth mode

Make the URL public (no auth required)

Make the URL public (no auth required)

Restore authenticated mode

Restore authenticated mode

Forward remote ports to local machine

Forward remote ports to local machine

View current network policy (from inside the sprite)

View current network policy (from inside the sprite)

Update network policy (from outside, via API)

Update network policy (from outside, via API)

Services

服务

List services

List services

Create a service

Create a service

Get service status

Get service status

View service logs

View service logs

Multi-Sprite Coordination

多Sprite协调

Run the same command across all sprites

Run the same command across all sprites

Lifecycle

生命周期

Create a new sprite

Create a new sprite

Destroy a sprite (irreversible)

Destroy a sprite (irreversible)

Internal Sprite Paths

Sprite内部路径