sprites-dev

你可以在本地机器上使用 sprite CLI 管理远程 Sprite VM。本技能介绍了用于从外部控制 Sprite 的本地端 CLI。（Sprite 内部运行的 Agent 也可以使用内置 Agent 上下文 /.sprite/docs/。）

Sprite 是运行在 Fly.io 上、具有硬件隔离的持久化 Linux VM，其持久文件系统由对象存储提供支持。

CLI 基础

sprite CLI 用于控制远程 Sprite。-s 标志指定要操作的 Sprite，-o 指定组织。

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

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

执行命令

sprite exec 是远程操作的主要工具。标准输出和标准错误会返回到本地终端。

# 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

重要： 每次调用 sprite exec 都会创建独立会话。环境变量、工作目录和 Shell 状态不会在调用之间保留。若要执行有状态的操作，请使用 bash -c "..." 串联命令，或使用 sprite console 启动交互式会话。

环境变量： -env 标志会将环境变量传递到远程会话，但多个 -env 标志只会应用最后一个。要传递多个变量，请使用逗号分隔的格式：

# WRONG — only BAR is set
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

文件传输

没有专用的文件传输命令。可使用 sprite exec 配合 cat 拉取文件，也可以通过管道传入内容：

# 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

检查点

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

# 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

频繁创建检查点。 在执行任何有风险的操作之前、切换上下文之前，以及任何进展顺利时，都应创建检查点。检查点几乎不花成本。

最近的 5 个检查点也会挂载在 Sprite 内的 /.sprite/checkpoints/，可直接检查文件，无需还原。

网络

每个 Sprite 都会获得一个公开的 HTTPS URL：https://<name>-<org>.sprites.dev/，默认路由到端口 8080。

# 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

网络出口策略通过 Sprites REST API 管理，而非 CLI：

# 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"}]}'

网络策略只能从外部修改。Sprite 无法更改自身策略。

服务

服务是在 Sprite 内运行的长时间运行进程，可在重启和休眠后持续存在。

# 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

可以将一个服务指定为 HTTP 服务（接收发往 Sprite URL 的代理请求）。

多个 Sprite 协同

跨多个 Sprite 工作时，使用 sprite list 查看所有 Sprite，然后按名称指定目标：

# Run the same command across all sprites
for s in $(sprite list); do
  echo "=== $s ==="
  sprite exec -s "$s" -- <command>
done

每个 Sprite 都完全隔离，不共享可变状态。请通过明确的通信方式进行协同：共享 Tigris 存储桶中的文件、HTTP 端点或 Git 仓库。

生命周期

# Create a new sprite
sprite create <name>
sprite create -o <org> <name>

# Destroy a sprite (irreversible)
sprite destroy <name>

Sprite 在空闲时会自动休眠（没有活动命令、TCP 连接、TTY 会话或正在运行的服务）。下次执行 sprite exec、sprite console 或向其 URL 发送 HTTP 请求时，会自动唤醒。磁盘上的所有内容都会在休眠周期之间保留，运行中的进程则不会。守护进程请使用服务。

设置开发 Sprite

创建新的 Sprite 后，请设置 Tailscale 并安装 dotfiles。Tailscale 可提供稳定的主机名以供 SSH 使用，并启用来自 Mac 的 1Password SSH Agent 的 Agent 转发。

1. 安装 Tailscale 和 dotfiles

传入 TS_AUTHKEY 和 TS_HOSTNAME，以便 install.sh 完成 Tailscale 的端到端设置：

# Mint an ephemeral tag:dev key via the Tailscale OAuth client (see agent_docs/secrets.md)
_tok=$(curl -fsS -u "$(op read 'op://Employee/Tailscale OAuth Dev/Client ID' --account industryvault.1password.com):$(op read 'op://Employee/Tailscale OAuth Dev/Client secret' --account industryvault.1password.com)" -d grant_type=client_credentials https://api.tailscale.com/api/v2/oauth/token | jq -r .access_token)
TS_AUTHKEY=$(curl -fsS -X POST -H "Authorization: Bearer $_tok" -H "Content-Type: application/json" -d '{"capabilities":{"devices":{"create":{"reusable":false,"ephemeral":true,"preauthorized":true,"tags":["tag:dev"]}}},"expirySeconds":600}' https://api.tailscale.com/api/v2/tailnet/-/keys | jq -r .key)
sprite exec -s <name> -env "TS_AUTHKEY=$TS_AUTHKEY,TS_HOSTNAME=<name>" -- bash -c "curl -fsSL https://raw.githubusercontent.com/kylelundstedt/dotfiles/master/install.sh | bash"

从 Mac 验证 SSH 连接：

ssh -o StrictHostKeyChecking=accept-new <name> echo ok

验证成功后再继续。

2. 克隆项目仓库

Mac 的 SSH 配置会将 1Password Agent 转发到 *.ts.net 主机（ForwardAgent yes）。这意味着执行 ssh <name> 后，Sprite 即可访问你的 GitHub SSH 密钥，无需令牌。直接克隆：

ssh <name> git clone [email protected]:<org>/<repo>.git /home/sprite/<repo>

首次通过 Tailscale SSH 登录时，会自动启用 Git 提交签名（Shell 会检测转发的 Agent）。

3. 从 Zed 连接

zed ssh://sprite@<name>/home/sprite/<repo>

内部 Sprite 路径

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