sprites

Sprites

Sprite は、永続化されるハードウェア分離型の Linux 環境です。セッション間でファイルシステムが保持され、パブリックホスト名が割り当てられ、切断後もサービスが稼働し続け、数秒でスナップショットの作成と復元を行えます。

まず最初に、どこで実行しているかを確認してください。 すべての操作には 2 つの形式があり、間違った方を選ぶとターンを無駄にします。

ステップ 1：実行環境を判定する

test -S /.sprite/api.sock && echo inside || echo outside

結果	意味	使用するコントロールプレーン
inside	エージェントが Sprite 内で実行されています	/.sprite/bin/sprite-env にある sprite-env CLI
outside	エージェントがラップトップ、CI ランナー、または別のホストで実行されています	sprite CLI、Sprites MCP サーバー、または REST API

結果はセッション中にキャッシュしてください。セッションの途中で変わることはありません。

2 つのコントロールプレーンは相互に置き換えられません。

• sprite-env はローカル API ソケットと通信します。常に現在の Sprite に対して動作し、Sprite 名は必要ありません。他の Sprite を認識したり操作したりすることはできません。
• sprite はネットワーク経由で https://api.sprites.dev と通信します。ほとんどのコマンドには対象の Sprite（-s <name>）が必要で、Sprite の作成や削除もできます。

Sprite の外部から sprite-env を呼び出さないでください。また、Sprite 内から、すでに実行中の Sprite を管理するためにリモート MCP ツールや sprite -s <self> を使用しないでください。どちらのバイナリもインストールされていない場合の代替手段については、環境の判定を参照してください。

ステップ 2：必要最小限の操作を選ぶ

目的	Sprite 内	Sprite の外部	リファレンス
環境を特定する	sprite-env info	sprite list、sprite url -s <name>	environment-detection.md
コマンドを実行する	シェルで直接実行する	sprite exec -s <name> -- <cmd>	remote.md
プロセスを稼働状態に保つ	sprite-env services create ...	sprite exec -s <name> -- sprite-env services create ...	services.md
プレビュー URL を公開する	サービスで --http-port を指定する	同様に指定し、さらに sprite url を実行する	services.md
状態のスナップショットを作成／ロールバックする	sprite-env checkpoints create	sprite checkpoint create -s <name>	checkpoints.md
ファイルを出し入れする	通常のファイルツール、または git clone	sprite file push / sprite file pull	files.md
アウトバウンドドメインを許可または拒否する	内部からは読み取り専用	sprite api .../policy/network	network-policy.md
サードパーティ API にアクセスする	api.sprites.dev/v1/gateway のゲートウェイ	Sprite 内でゲートウェイ呼び出しを実行する	api-gateway.md
環境を作成または削除する	不可	sprite create / sprite destroy	remote.md

基本的な手順

1. Sprite の内外を判定します。コントロールプレーンを一度選択します。
2. 名前で対象の Sprite を正確に特定します。外部から操作する場合は、sprite list または .sprite/config（sprite use）で確認してください。名前を推測してはいけません。
3. 変更を加える前に状態を確認します。まずサービスの状態、ログ、チェックポイントの一覧を読み取ります。
4. リスクのある作業の前に、重要な状態のチェックポイントを作成します。チェックポイントの作成には数秒しかかかりません。
5. 作業を実行します。範囲が限定されたコマンドには exec を使い、呼び出し後も実行を続ける必要があるものにはサービスを使います。
6. 実際の出力で確認します。終了ステータス、サービスの状態、ログ、HTTP プローブなどを確認してください。
7. Sprite 名、URL とその認証方式、およびチェックポイント ID があれば報告します。

安全規則

• Sprite の URL はパブリックな場合があります。環境変数、トークン、キーファイル、フィルタリングされていないログ、管理者用エンドポイントを Sprite のサービスから公開してはいけません。
• checkpoint restore はファイルシステムを巻き戻し、それ以降の変更を破棄します。実行前にその旨を説明し、承認を得てください。
• destroy は取り消せません。サービス、チェックポイント、URL も一緒に削除されます。明確な意思を確認してから実行してください。
• ネットワークポリシーの更新は、ルールセット全体を置き換えます。現在のポリシーを読み取り、統合してから書き込んでください。

詳しくは安全性を参照してください。

リファレンス

作業に合ったものをお読みください。それぞれ単独で完結しています。

• environment-detection.md — 内部か外部かの判断、どちらの CLI をインストールするか、認証の設定。
• remote.md — 外部からのスプライト操作：作成、一覧表示、実行、セッション、ファイル、ポート、破棄。
• services.md — 長時間実行プロセス、サービスマネージャー、公開 HTTP URL。
• checkpoints.md — スナップショット、ロールバック、マウントされたチェックポイントからの古いファイルの読み取り。
• network-policy.md — 外向きエグレスルールと、読み取り・変更・書き込みによる更新手順。
• api-gateway.md — ゲートウェイによって認証情報が注入されるサードパーティ API（GitHub、Slack など）。
• cli.md — sprite-env および sprite コマンドの全容。
• http-api.md — HTTP クライアントのみを利用するエージェント向けの、両方の CLI が使用する REST エンドポイント。
• files.md — コードやデータの出し入れ。
• safety.md — 確認ルールと公開範囲の制限。