sprites-dev

ローカルマシンから sprite CLI を使ってリモートの Sprite VM を管理します。このスキルでは、外部から Sprite を制御するためのローカル側の CLI について説明します。（Sprite 内部で実行されるエージェント向けの組み込みコンテキストも、/.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 を実行するたびに、別のセッションが開始されます。環境変数、作業ディレクトリ、シェルの状態は呼び出し間で引き継がれません。状態を維持して作業するには、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

ファイル転送

専用のファイル転送コマンドはありません。ファイルを取得するには cat を使って sprite exec を実行するか、コンテンツをパイプで渡します。

# 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

ネットワークの送信ポリシーは CLI ではなく、Sprites REST API を使って管理します。

# 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

1 つのサービスを HTTP サービスとして指定できます（Sprite の URL へのプロキシリクエストを受け取ります）。

複数 Sprite の連携

複数の Sprite をまたいで作業する場合は、sprite list でフリートを確認し、名前を指定してそれぞれを操作します。

# 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 エージェントからエージェント転送できるようになります。

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 エージェントを *.ts.net ホストに転送します（ForwardAgent yes）。そのため、ssh <name> を実行すると Sprite から GitHub の SSH キーを使用できます。トークンは不要です。そのままクローンしてください。

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

Tailscale SSH による初回ログイン時に、Git のコミット署名が自動的に有効になります（シェルが転送されたエージェントを検出します）。

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/ — ユーザーのホームディレクトリ