managing-streamlit-apps

Streamlit アプリの管理

Streamlit アプリは、PostHog 内の隔離されたサンドボックスで実行される Python データアプリです。 各アプリのコードは変更不可のバージョンとして保存され、そのうち 1 つがアクティブになり、サンドボックスプロセスがアクティブなバージョンを提供します。 ライフサイクル全体は、streamlit-apps-* MCP ツールで管理します。

基本的な流れ：作成 → ソースの設定 → 起動 → 共有

1. streamlit-apps-create を name とともに実行します（description、cpu_cores 0.25–8、memory_gb 0.5–16 は任意で、デフォルトはそれぞれ 0.5／1 です）。 アプリは作成されますが、まだコードはありません。
2. streamlit-apps-set-source に、完全な app.py のソースを 1 つの文字列として渡します。 追加ファイルも同じ呼び出しで渡せます。files はプロジェクト内の相対パスをテキストに対応付けます（ヘルパーモジュール、CSV、JSON）。assets はパスを base64 に対応付けます（Parquet、画像）。 これによりバージョン 1 が作成され、アクティブになります。 writing-streamlit-apps スキルに従ってソースを記述してください。特に、PostHog のデータには posthog_apps.query() を使い、import posthog は使わないでください。
3. streamlit-apps-start を実行します。 すぐに応答が返され、サンドボックスは非同期で起動します。
4. status が running になるまで streamlit-apps-status をポーリングします（通常は 1 分もかかりません）。 error になった場合は、last_error を確認してください。下記の「トラブルシューティング」を参照してください。
5. アプリを共有します。create／get／start から返される _posthogUrl（/streamlit-apps/{short_id}）が、PostHog 内のアプリのページです。 そのリンクを共有相手に渡します。 閲覧者は、プロジェクトへのアクセス権を持つ PostHog アカウントでログインする必要があります（アプリは認証済み iframe 内に表示され、公開 URL はありません）。

アプリが読み取るデータ

アプリのクエリは、アクティブなバージョンを作成した人のデータアクセス権で実行されます。ソースを設定すると、あなたが読み取れるデータをアプリも読み取ります。 アプリを閲覧できる人は誰でもその結果を見られるため、アプリの公開はプロジェクト全員へのデータ共有として扱ってください。 バージョンの作成者が削除されている場合、そのアプリは起動できません。新しいバージョンをアップロードして修正してください。

コードの更新

既存のアプリを変更する場合は、古いコピーで新しい作業を上書きしてしまわないよう、次の 2 段階で行います。

1. streamlit-apps-get-source でアクティブなバージョン（または古いバージョンを指定する version_number）を読み取ります。 version_number、すべてのファイルのマニフェスト、および各テキストファイルの内容が返されます。 バイナリファイルは、内容なしで表示されます。 大規模なアプリの場合は、paths（カンマ区切り）を渡して、必要なファイルだけを読み取れます。
2. base_version にその version_number を指定して、streamlit-apps-edit-source を実行します。 file_edits には、ファイルごとの完全一致する old → new テキスト置換を指定します。create_files で新しいテキストファイルを追加し、delete_files でファイルを削除します。 各 old は正確に 1 回だけ一致する必要があるため、一意に特定できるよう前後の行を十分に含めてください。 変更しないファイルは、新しいバージョンでもバイト単位でそのまま維持されます。

読み取り後にアクティブなバージョンが変わっていた場合、edit-source は current_version とともに 409 を返します。 これは、別のセッションがバージョンを公開した場合や、誰かがアプリを古いバージョンに戻した場合に発生します。 current_version を改めて読み取り、そのバージョンに対して編集をやり直してください。 コピーを強制的に反映するために set-source に切り替えてはいけません。

streamlit-apps-set-source は、新しいアプリを作成するとき、または全面的に書き換えるときに使用してください。 このツールはすべてのファイルを置き換えるため、files と assets も再度渡してください。各バージョンに保存されるのは、その呼び出しで渡された内容だけです。

どちらのツールも次のバージョンを作成し、アクティブにします。 実行中のサンドボックスは停止され、古いコードを提供し続けないようになります。新しいバージョンを提供するには、その後 streamlit-apps-start を呼び出してください。 バージョンは変更不可ですが、永久には保持されません。streamlit-apps-versions には最新の 50 件が一覧表示され、30 日を超えた非アクティブなバージョンはコードとともに削除されます。 ロールバック用のツールはありません。ロールバックするには、streamlit-apps-get-source で古いバージョンを読み取り、そのファイルを set-source で再設定します。 バイナリアセットはそこでインライン化されないため、アセットを含むアプリのロールバックには、それらのファイルの保存済みコピーも必要です。

停止、アイドル状態、削除

• streamlit-apps-stop はサンドボックスを停止します。コードとバージョンは変更されません。後で再び起動する際のコストは低く抑えられます。
• アイドル状態のサンドボックスは、一定期間アクティビティがないと自動的に停止します。アプリが停止していても正常な状態であり、エラーではありません。必要なときに再び起動してください。
• streamlit-apps-delete は、サンドボックスを停止してアプリを論理削除します。この会話で作成していないものを削除する前に、ユーザーに確認してください。

トラブルシューティング

• status: error と last_error: "Start failed: ..." が表示される — サンドボックスのプロビジョニングまたは起動に失敗しました。streamlit-apps-start を一度再試行してください。それでも解決しない場合は、last_error をユーザーに伝えてください（プロビジョニングの失敗は通常、アプリ側ではなくプラットフォーム側の問題です）。
• ツールの呼び出しで 403「Streamlit apps is not available.」が返される — この組織では streamlit-apps 機能フラグがオフになっています。これは展開上の制限であり、修正できるエラーではありません。ユーザーに伝えてください。
• アプリは動作するものの、アプリ内のクエリが失敗する — アプリのコードに関する問題です。writing-streamlit-apps を参照してください（ブリッジの制限：実行時間 30 秒、クエリあたりのメモリ 256 MB）。
• set-source の後もアプリに古いコードが表示される — 「set-source の後に起動する」手順を省略しています。サンドボックスは停止しているため、起動する必要があります。

名前の変更とサイズの変更

streamlit-apps-update は、アプリの名前、説明、cpu_cores（0.25～8）、または memory_gb（0.5～16）を変更します。渡したフィールドのみが変更されます。 新しいサイズ設定は、次回のサンドボックス起動時に適用されるため、実行中のアプリのサイズを変更した後は、停止してから再起動してください。 デフォルト（CPU 0.5／メモリ 1 GB）は、一般的なダッシュボードアプリに適しています。 memory_gb を増やすのは、アプリ自体が大きな DataFrame をメモリ上に保持する場合に限ってください。HogQL ブリッジクエリの上限 256 MB はサーバー側の制限であり、サンドボックスのサイズを変更しても変わりません。そのため、サンドボックスを大きくしてもクエリの失敗は解決しません。