apps.json を編集する: 保存場所、再読み込み、復旧の方法

Moonpool が管理するすべてのアプリは、apps.json の 1 つのエントリーです。編集は、アプリエディター (アプリを追加 / アプリを編集のダイアログ) でも手作業でも行えます。どちらも同じファイルに書き込みます。ツールの結果やメッセージの一部では、このファイルをマニフェストと呼んでいます。

設定の保存場所

モード	設定フォルダー
インストール版 (Windows)	%USERPROFILE%\.moonpool\moonpool-config\
ポータブル	moonpool.exe の隣の moonpool-config\ (.moonpool\ フォルダーの中)
Linux	$XDG_CONFIG_HOME/Moonpool/、なければ ~/.config/Moonpool/

apps.json はそのフォルダーにあり、次のものと並んでいます。

項目	用途
apps.json.history\	直近 10 件の有効な apps.json を保持するロールバック用のリング。
settings.json	アプリの設定。settings.jsonを参照してください。
cli-output\<id>\	アプリごとのセッションログ。ログを参照してください。
moonpool.log	デバッグログ。デバッグ情報をファイルに記録 がオンの間に書き込まれます。
icons\	省略可能な <id>.png (.ico、.svg、.jpg、.jpeg、.webp も可) のアイコン上書き。
state.json	数秒ごとに更新される、状態のスナップショット。
dumps\	dump、read-config、restore-config 動詞が書き出すファイル。
mcp_seen.json	MCP ヘルパーが使われたことのあるアプリ。
window-state.json	ハブウィンドウのサイズと位置。
AI-README.md	AI エージェント向けのガイド。起動のたびに書き直されます。

どれをバックアップすればよいかは、バックアップと復旧にあります。

初回起動時に、Moonpool は apps.json にサンプルのエントリーを書き込みます。すでにあるファイルが上書きされることはありません。

編集

• ダイアログ。 サイドバー上部の … メニューの アプリを追加 を使います。アプリを変更するには、行の鉛筆を使うか、右クリックして 編集 を選びます。ダイアログは、検証してすぐに保存します。
• 手作業。 同じメニューの apps.json を編集 で、既定のエディターでファイルが開きます。保存してから、メニューの 再読み込み を選びます (または F5 か Ctrl+R を押します)。

手作業の編集は、再読み込みするまで反映されません。再読み込みはファイルを読むだけで、書き換えません。

ダイアログから保存すると、ファイル全体が、整形されインデントされた形式で書き直されます。Moonpool が知らないキーは削除されます。JSON にはコメントがないので、メモは note フィールドに残してください。

構造

ファイルは、オブジェクトの JSON 配列です。すべてのエントリーで 4 つのキー、id、name、group、type が必須です。それ以外はすべて省略可能です。アプリのフィールドを参照してください。

apps.json

[
  { "id": "site", "name": "Site", "group": "Web apps", "type": "web",
    "cwd": "C:\\code\\site", "command": "npm run dev", "port": 5173,
    "url": "http://localhost:5173", "openBrowser": true }
]

グループは、ファイルの中で最初に現れた順にサイドバーに表示されます。

再読み込みの動作

再読み込みは、Moonpool がメモリ上に持つ一覧を、ファイルの内容で置き換えます。起動、停止、再起動は、ボタンをクリックした時点でエントリーを読むので、編集した command、cwd、env、終了方法の設定は、次にそのアプリを起動または再起動したときに適用されます。再読み込みで何かが再起動されることはありません。すでに動いているアプリは、起動したときの設定のまま動き続けます。

検証

Moonpool は、ファイルを読み込むとき、保存のたび、エージェントが書き込むたびに、ファイル全体を検証します。不正なエントリーが 1 つあるだけで、ファイル全体が拒否されます。

ルール	エラーに含まれる文字列
有効な JSON でない、必須のキーがない、または値の型が違う	JSON パーサーのメッセージ
id が空、- で始まる、または英数字と .、_、- 以外の文字を含む	invalid id
2 つのエントリーが同じ id	duplicate app id
name が空白	has an empty name
group が空白	has an empty group
type が desktop、web、static、cli のいずれでもない	unknown type
port が 0 (65535 を超える port は解析に失敗します)	invalid port 0
url のない static エントリー	requires a url
command のない、それ以外の type	requires a command

エラーでは、位置でエントリーが示されます。たとえば次のとおりです。

apps.json entry 2 (site) requires a command

id

id は、エントリーの恒久的なキーです。ログフォルダーとアイコンファイルの名前になり、moonpool.exe launch <id> やエージェントに渡す値でもあります。ダイアログは、アプリを追加するとき、名前から id を作ります。名前を小文字にし、a から z と 0 から 9 以外の文字の連続を 1 つの - に置き換え、両端の - を取り除きます。結果が空なら app になります。その id がすでに使われていれば、-2、-3 のように付け足します。作成後に id が変わることはないので、アプリの名前を変更しても id はそのままです。Habit Tracker という名前の id は habit-tracker になります。

ファイルが不正なとき

• 再読み込み時、検証に失敗したファイルには手を加えず、Moonpool は最後に読み込めた一覧を保持します。サイドバーの上にエラーを示すバナーが表示され、ファイルを開くボタンも付きます。一覧は使えますが、薄く表示されます。apps.json にエラーがあるときを参照してください。
• 起動時 は、壊れたファイルでは保持できる一覧がないので、Moonpool はアプリなしで起動し、バナーにその旨が表示されます。ファイルを修正して 再読み込み を選ぶか、スナップショットを復元します (下記、または moonpool_restore_config ツール)。
• どちらの場合も、ファイルが再び読み込めるまで、ダイアログからの保存 (および名前の変更、削除、アイコンの設定) は拒否されるので、壊れたファイルが上書きされることはありません。ファイルを修正して 再読み込み を選んでください。
• ダイアログ、エージェント、復元から の不正な変更は拒否され、ディスク上のファイルはそのまま残ります。

Moonpool は、直近 10 件の正常な apps.json を apps.json.history\ に保持します。ロールバックの方法はバックアップと復旧にあります。症状と対処はトラブルシューティングにあります。

エージェント

AI エージェントは、ファイルではなく Moonpool の MCP ツールを通して apps.json を変更してください。そうすれば、古い書き込みや不正な書き込みは拒否され、サンドボックス内のエージェントが非公開のコピーを編集することもありません。MCP ツールを参照してください。