freebox

freeBox Loader — Getting Started

対象読者: freeBox Loader を hsBox に初めてインストールするユーザー
ドキュメントバージョン: v1.0.0
ステータス: v1.0.0 リリース版

1. 概要

freeBox Loader は、hsBox 上で動作する Plugin 管理サーバーです。Web UI（Manager）から Plugin モジュールを取得・インストール・管理できます。

freeBox Loader が目指すのは「自由な拡張を、すべての人に」というコンセプトです。オープンな仕様に沿った Plugin であれば、ユーザー自身が実装・追加でき、デバイスメーカーやサービス事業者も Plugin として参加できる──「使う側」だけでなく「作る側」にも開かれたオープン拡張プラットフォームを目指しています。当面は hsBox 上での動作を前提としますが、マルチプラットフォーム展開も構想しています。

コンセプトの詳細:

2026年発進。自由な拡張を、すべての人に。OSSプロジェクト『freeBox』の始動を支援します（2026-01-07）

freeBox Loaderで、スマートホーム連携はここが変わる（2026-04-15)

インストール後は以下の URL で Manager UI にアクセスできます：

http://<hsBox のIPアドレス>/freebox/manager/

2. 事前準備：hsBox のセットアップ

freeBox Loader をインストールする前に、hsBox 本体のセットアップが必要です。

2-1. hsBox イメージ・パッケージの入手

以下の URL（Vector のサイト）から hsBox のパッケージをダウンロードします。

https://www.vector.co.jp/soft/cmt/unix/net/se525279.html

ダウンロードページの 「そのソフトを今すぐダウンロード」 ボタンを押してダウンロードします。

ダウンロードされる ZIP ファイルの例：

hsbox1030100.zip  (約 695 MB)

ZIP ファイルを解凍すると、以下のファイルが含まれています：

ファイル名	内容
`hsbox_B0310mini.imz`	hsBox のディスクイメージ（約 727 MB）
`利用者マニュアル1030100.pdf`	セットアップ手順の詳細マニュアル
`hsbox使用許諾契約書202508.pdf`	使用許諾契約書
`1030100登録情報.txt`	バージョン情報等
`説明書要約.txt`	手順の概要

2-2. hsBox USB メモリの作成

利用者マニュアル1030100.pdf の手順に従って hsBox の USB メモリを作成します。以下は手順の概要です。詳細は PDF ファイルを参照してください。

USB メモリの要件：

USB 3.2 以上
容量 32 GB 以上
新品の USB メモリを使用してください

作業手順（概要）：

(1) hsBox イメージを USB メモリに書き込む

hsbox_B0310mini.imz を USB メモリに書き込みます。書き込み方法は 利用者マニュアル1030100.pdf を参照してください。

(2) Windows 11 環境で初期ファイルを追加する

書き込み済みの USB メモリを Windows 11 PC に挿し、エクスプローラーで USB メモリを開きます。 HSBox_aps13.ps1 を右クリックして実行します。これにより Ubuntu 24 の必要なファイルが USB メモリに追加されます。

ここまでの作業が完了した USB メモリを PC に挿して、次の手順に進みます。

2-3. hsBox の初回起動

(1) BIOS/UEFI 設定で USB 起動を最優先にする

PC に USB メモリを挿した状態で電源ボタンを押します。起動直後に ESC・F2・F10・DEL などのキーを押して BIOS/UEFI 設定画面を開き、ブート順序を USB メモリが最優先になるように設定します。

設定方法は PC（メーカー）ごとに異なります。詳しくは各 PC の公式ドキュメントを参照してください。

(2) GRUB 起動選択画面

起動すると GRUB のメニュー画面が表示されます。 Enter キーを押すか、30 秒待つと自動的に起動処理が始まります。

(3) 起動完了の確認

起動には 1 分ほどかかります。最初にグラフィカルな画面が表示されますが、すぐに CUI モードに切り替わります。起動が完了すると、接続しているスマートデバイスへの認識通知が行われ、画面に以下が表示されます：

hsBox へのアクセス URL
スマートフォンで読み込める QR コード

この画面が表示されれば起動完了です。

所要時間について: 「1 分ほど」は参考値です。実際の起動時間は使用するマシンのスペック（CPU・ストレージ速度・メモリ容量等）によって変動します。

Google Nest Hub などの認識済みデバイスには「hsBox がこのデバイスを認識しました」の通知が届きます。

2-4. 管理画面へのアクセスとライセンス登録

(1) 管理画面にアクセスする

起動画面に表示された URL をブラウザで開きます。

ログイン ID・パスワードは 利用者マニュアル1030100.pdf を参照してください。また、パスワードの変更手順も同 PDF に記載されています。

(2) ライセンスを登録する

管理画面のトップから 「ライセンス」 または 「ライセンス情報」 を選択します。未登録の場合は「ライセンス未登録」と表示されています。

以下の 3 項目を入力して 「ライセンス登録」 ボタンを押します：

項目	内容
hss ユーザー名	hss ユーザー登録時に決めたユーザー名
hss パスワード	hss ユーザー登録時に決めたパスワード
hsbox ライセンス	ライセンスコード

hss ユーザー登録の方法: hss ユーザー登録の手順は以下を参照してください。

公式サポートページ: https://hoscm.com/hsbox/support/

YouTube 動画: https://youtu.be/44RWocuUASA

登録が受け付けられると以下のメッセージが表示され、ライセンスパッケージの適用処理が始まります：

■ライセンス登録処理中： XXXXXXXXXXXX
ライセンス登録完了後、自動的にシャットダウンします。
▼処理要求「ライセンス登録処理」を受付ました。

(3) シャットダウンと再起動

ライセンスパッケージの適用が完了すると自動的にシャットダウン処理が行われます。停止ログの後に「ENTER を押して」と表示されたら Enter キーを押してシャットダウンします。

電源が切れてから 10 秒以上待って から電源を入れ直してください。

再起動後の管理画面で 「スマートサービス連携」 などのメニューが表示されていれば、ライセンスパッケージの適用成功です。

2-5. 固定 IP アドレスの設定（推奨）

必要に応じて hsBox に固定 IP アドレスを設定します。

管理画面から 「システム情報」→「固定 IP アドレス」 を選択し、使用する IP アドレスを設定します。

例: 192.168.2.48/24

IP アドレスが他のデバイスと重複しないことを確認してから設定してください。

2-6. NAS のマウント設定

freeBox Loader の NAS 連携機能を使用する場合は、NAS のマウント設定を行います。

NAS を使用しない場合はこの手順をスキップできます。

(1) マウントポイントの作成

hsBox に SSH でログインし、マウントポイントを作成します：

sudo su -
mkdir -p /mnt/nas

(2) 手動マウントで動作確認

以下のコマンドで NAS をマウントし、正常にアクセスできるか確認します：

sudo mount -t cifs //<NAS の IP アドレス>/<共有フォルダパス> /mnt/nas \
  -o username=<ユーザー名>,password=<パスワード>,\
uid=$(id -u hsbox),gid=$(id -g hsbox),\
file_mode=0664,dir_mode=0775,_netdev,vers=3.0,\
rsize=4194304,wsize=4194304,noperm

マウント後、ls /mnt/nas でファイルが見えれば成功です。

noperm オプションについて: Plugin がキャプチャ画像やログファイルを NAS に書き出す際、CIFS のクライアント側権限チェックで書込が失敗する場合があります。noperm を指定するとクライアント側の権限チェックをスキップし、NAS 側のアクセス制御に委譲します。NAS 側で適切な書込権限を設定してください。

コマンドのユーザー名・パスワード・IP アドレス・共有フォルダパスは環境に合わせて指定してください。

(3) 起動時に自動マウントする設定

手動マウントが成功したら、同じマウントコマンドを起動スクリプトの末尾に追記します：

nano /home/hsbox/sh/hs_startup.sh

ファイルの末尾に手順 (2) で使用したマウントコマンドを追加して保存します。

ここまでの作業が完了したら、事前準備は完了です。

3. freeBox Loader のインストール

hsBox の管理画面（システムアップデート機能）から freeBox Loader をインストールします。

3-1. インストールファイルの入手

以下の URL から freebox-base.hbx をダウンロードします：

https://github.com/hoscm/freebox/releases/tag/v1.0.0

リリースページにある freebox-base.hbx をクリックしてダウンロードしてください。

3-2. インストール手順

(1) hsBox 管理画面にアクセスする

ブラウザで以下の URL を開きます：

http://<hsBox の IP アドレス>/

(2) システムアップデート画面を開く

管理画面のタブメニューから 「システムアップデート」 をクリックします。

(3) インストールファイルを選択してアップロードする

「■オプション」セクションの 「ファイル選択」 ボタンを押し、ダウンロードした freebox-base.hbx を選択します。

「[オプションファイルアップロード]」 ボタンを押します。

以下のメッセージが表示されればアップロード成功です：

freebox-base.hbx をアップロードしました。
▼処理要求「オプション freebox-base.hbx の適用」を受付ました。

インストール処理が自動的に実行されます。

3-3. インストール確認

インストール完了後、Manager UI がアクセス可能であることを確認します。

ブラウザで以下の URL を開きます：

http://<hsBox の IP アドレス>/freebox/manager/

正常な状態：

Manager UI のトップページが表示される
画面下部の StatusBar に以下の 5 項目が表示される

項目	正常時の表示
freebox	`running`
NAS	`connected` または `disconnected`（NAS 未接続時）
apache2	`running`
Scheduler	`0 job(s)` 以上
Index	`0 modules` 以上

NAS が disconnected の場合: NAS が接続・マウントされていない場合は disconnected と表示されます。freeBox Loader 本体の動作には影響しません。

3-4. インストール内容（参考）

インストールにより、以下のファイルが hsBox に配置されます：

パス	内容
`/home/hsbox/freebox/box_webserver.py`	freeBox Loader メインサーバー
`/home/hsbox/freebox/freebox_config.ini`	設定ファイル（初回は自動生成）
`/home/hsbox/freebox/plugins/`	Plugin モジュール格納ディレクトリ
`/home/hsbox/freebox/data/`	インデックスキャッシュ等のデータディレクトリ
`/home/hsbox/www/freebox/index.php`	hsBox タブ連携ファイル
`/etc/apache2/conf-enabled/freebox.conf`	Apache2 プロキシ設定
`/etc/systemd/system/freebox.service`	systemd サービス定義

設定ファイルについて: 既に freebox_config.ini が存在する場合（再インストール時）は、既存の設定を保持したまま新しい設定項目のみ追加されます。設定が失われることはありません。

4. Manager UI の基本操作

Manager UI は freeBox Loader の中心的な操作画面です。Module モジュールの一覧表示・インストール・アンインストール・設定変更を行います。

4-1. 画面構成

Manager UI は 4 つのエリアで構成されています。

┌─────────────────────────────────────────────────────┐
│ ① TopNav（上部ナビゲーション）                          │
├──────────────┬──────────────────────────────────────┤
│              │                                       │
│ ② Sidebar     │ ③ Main エリア                         │
│   ・Module     │    ・PageHeader（タイトル・操作ボタン）  │
│     List      │    ・StatsRow（4 つの統計カード）       │
│   ・Scheduler │    ・Toolbar（検索・フィルタ）          │
│   ・Settings  │    ・ModuleGrid（モジュール一覧）       │
│              │                                       │
└──────────────┴──────────────────────────────────────┘
│ ④ StatusBar（下部ステータスバー）                       │
└─────────────────────────────────────────────────────┘

4-2. TopNav（上部ナビゲーション）

画面上部の固定バーです。左側に「freeBox Loader」のロゴ、右側に hsBox 管理画面への戻りリンクが表示されます。

項目	内容
freeBox Loader ロゴ	freeBox Loader のロゴ表示（クリック動作なし）
状態インジケーター	緑のドット + `freebox.service running` で稼働状態を示します
◀ hsBox Top	hsBox 管理画面のトップに戻ります
SP	hsBox 管理画面のスマートフォン版に移動します

3 つのタブを切り替えるためのナビゲーションです。

タブ	アイコン	内容
Module List	⬡	モジュール一覧（メイン画面）
Scheduler	●	登録されているスケジューラジョブの一覧
Settings	⚙	freeBox Loader の設定変更

サイドバーの右端には、各タブに関連する数値（モジュール数・ジョブ数）がバッジで表示されます。

4-4. StatusBar（下部ステータスバー）

画面最下部の固定バーで、freeBox Loader と hsBox 全体の稼働状態を表示します。30 分ごとに自動更新されます。

更新間隔について（v1 暫定値）: v1 ではポーリングの二重リクエスト問題への暫定対処として、自動更新間隔を 30 分（実質ほぼ無効に近い間隔）に設定しています。最新状態をすぐ確認したい場合はブラウザの再読み込み（F5）を行ってください。本仕様は v1.1.0 で再検討予定です（将来は IoT イベント集約実装と合わせて WebSocket / SSE への移行を計画）。

項目	値の意味
freebox	`running` = freeBox Loader 本体が稼働中
NAS	`connected` = NAS マウント済み / `disconnected` = 未接続
apache2	`running` = Apache2 リバースプロキシが稼働中
Scheduler	登録されているスケジューラジョブの件数
Index	インデックス JSON に登録されているモジュール数

4-5. Module List 画面

サイドバーの Module List をクリックすると表示される、freeBox Loader のメイン画面です。

StatsRow（4 つの統計カード）:

カード	内容
Index Modules	インデックス JSON に登録されている公開モジュール数
Deployed	インストール済みモジュール数
Local / Private	インデックス未登録の手動インストール済み private モジュール数
Scheduler Jobs	登録されているスケジューラジョブの件数

Toolbar（検索・フィルタ）:

検索ボックス：モジュール名・ID で絞り込み
フィルタタブ：ALL / 🟢 public / 🟡 restricted / 🔴 private
↺ Refresh Index：GitHub からインデックスを再取得（成功時はモジュール一覧が最新化されます）
＋ Deploy Module：ローカルの .hbx ファイルをアップロードしてインストール

ModuleGrid（モジュール一覧）:

各モジュールはカード形式で表示されます。カードの上端の色がステータスを示します：

色	ステータス	意味
緑 🟢	`public`	誰でも使える公開モジュール
黄 🟡	`restricted`	動作確認中・制限付き公開モジュール
赤 🔴	`private`	インデックス未登録の非公開モジュール

各カードには [詳細] [Deploy] [Remove] などの操作ボタンが表示されます。

5. Plugin モジュールのインストール

freeBox Loader の Manager UI から、3 種類のステータス（public / restricted / private）のモジュールをインストールできます。それぞれインストール時の確認ステップが異なります。

5-1. public モジュールのインストール

用途: 動作確認済みの公開モジュール。確認なしですぐにインストールできます。

手順:

(1) Module List 画面で対象のモジュールカードを探す

カード上端が緑色のモジュールが public です。

(2) [▼ Deploy] ボタンをクリック

確認ダイアログは表示されません。即座にインストール処理が始まります。

(3) インストール完了の確認

カードに ✓ Installed バッジが表示されたらインストール成功です。

(4) 再起動を実行

画面上部に「Module の変更が完了しました。有効化するには hsBox 全体の再起動が必要です。」というオレンジ色のバナーが表示されます。

[🔄 今すぐ再起動] ボタンを押すか、hsBox 管理画面のシステム設定から再起動を実行してください。

⚠ v1 制限事項（再起動ボタン）: [🔄 今すぐ再起動] ボタンは hsBox 管理画面にリダイレクトしますが、現在の v1 ではトークン情報の引き継ぎが未対応のため、リダイレクト後 hsBox 側がログアウト状態になります。再ログイン後、hsBox 管理画面のシステム設定から再起動を実行してください。本件は v1.1.0 で改善予定です。

再起動の理由: v1 では Plugin のホットロード（再起動なしでの読み込み）は対応していません。再起動するまで新しいモジュールは動作しません。

5-2. restricted モジュールのインストール

用途: 動作確認中・制限付き公開モジュール。1 段階の確認ダイアログを経由します。

手順:

(1) カード上端が黄色のモジュールカードで [⚠ Deploy] をクリック

(2) 確認ダイアログが表示される

⚠ 限定公開 Module の Deploy 確認
このModuleは限定公開（restricted）ステータスです。
hoscm/freebox リポジトリにマージ済みですが、
まだ動作確認中のため一般公開前のバージョンです。

ダイアログ内のチェックボックス 「この Module が限定公開ステータスであることを理解した上で deploy します」 にチェックを入れます。

(3) [⚠ Deploy 実行] ボタンをクリック

(4) インストール完了 → 再起動

以降は public モジュールと同じ流れです（カードに ✓ Installed バッジ表示 → 再起動バナー → 再起動）。

5-3. private モジュールのインストール

用途: インデックスに登録されていない非公開モジュール。2 段階の確認を経由します。出所不明のコードを実行することになるため、慎重に確認してください。

⚠️ 重要: private モジュールは hoscm/freebox 公式リポジトリによる信頼性チェックを受けていません。悪意あるコードが含まれる可能性があります。自己責任での実行になります。

private モジュールのインストール方法は 2 通りあります：

A. インデックス登録された private モジュールを Manager UI からインストール（本節）
B. ローカルの .hbx ファイルをアップロードしてインストール（§6 参照）

A. インデックス登録された private モジュールのインストール

(1) カード上端が赤色のモジュールカードで [⚠⚠ Deploy] をクリック

(2) ステップ 1：リスク確認ダイアログ

🚨 非公開 Module の Deploy 確認
このModuleは hoscm/freebox リポジトリに登録されていません。
出所不明のコードを実行することになります。

「リスクを理解した上で、次のステップへ進みます」のチェックボックスにチェックを入れて [次へ →] をクリックします。

(3) ステップ 2：自己責任確認

最終確認：自己責任で実行することを明示的に宣言してください。

以下の 2 つが揃うまで [Deploy 実行] ボタンは押せません：

テキスト入力フィールドに Module ID を正確に入力（モジュールの id と完全一致する必要があります）
「この Module を自己責任で実行することを確認しました」のチェックボックスにチェック

両方が満たされたら [🚨 Deploy 実行] ボタンが有効になります。

(4) インストール完了 → 再起動

以降は public / restricted モジュールと同じ流れです。

6. ローカル .hbx ファイルをインストールする（private モジュール）

Manager UI から、ローカル PC にある .hbx ファイルを直接アップロードしてインストールできます。インデックスに登録されていない private モジュールの導入に使います。

6-1. .hbx ファイルとは

.hbx ファイルは freeBox の Plugin パッケージ形式です。実体は ZIP ファイルで、以下を含んでいます：

version.txt：モジュール ID とバージョン情報
<id>.py：Plugin 本体の Python コード
その他の依存ファイル（必要に応じて）

.hbx ファイルの作り方は hbx_build_tool_guide.md を参照してください。

6-2. アップロード手順

(1) [＋ Deploy Module] ボタンをクリック

Module List 画面の右上にある [＋ Deploy Module] ボタンを押します。アップロード用ダイアログが開きます。

(2) .hbx ファイルを選択

ダイアログ中央のドロップエリアをクリック、または .hbx ファイルを直接ドラッグ&ドロップします。

(3) ファイルが受理されたか確認

ファイル名とサイズが緑色で表示されれば受理 OK です：

mymodule.hbx (12.3 KB)

拡張子が .hbx 以外の場合：警告が表示され、[アップロード] ボタンは無効化されます。 ファイルサイズが 10 MB 超の場合:サーバー側でエラーになります。

(4) [▲ アップロード] ボタンをクリック

サーバーに送信され、自動的に展開・インストールされます。

(5) 結果メッセージの確認

成功時：

✓ <module_id> をインストールしました。
   再起動後に有効になります。

ダイアログは 2 秒後に自動で閉じます。

エラー時の主な原因：

エラーコード	原因
`invalid_extension`	拡張子が `.hbx` ではない
`invalid_hbx_format`	ZIP として展開できない・形式が不正
`invalid_version_txt`	`version.txt` が含まれていない
`already_installed`	同じ ID のモジュールが既にインストール済み

6-3. 既にインストール済みの場合（Re-deploy）

同じ ID のモジュールが既にインストール済みの場合、already_installed エラーになります。

v1 では、Manager UI からの上書きインストールは制限されています。以下の手順で対応してください：

(1) 既存モジュールを削除（§7 参照）

(2) .hbx を再アップロード

(3) hsBox を再起動

7. モジュールを削除する

不要になったモジュールは Manager UI から削除できます。削除後は元に戻すために再インストールが必要になります。

7-1. 削除手順

(1) Module List 画面で対象モジュールのカードを探す

インストール済みのモジュールには ✓ Installed バッジと [🗑 Remove] ボタンが表示されています。

(2) [🗑 Remove] ボタンをクリック

(3) 確認ダイアログが表示される

🗑 Uninstall 確認
この Module をアンインストール（削除）します。
plugins/ ディレクトリからプラグインファイルを削除します。

⚠ Uninstall 後は hsBox 全体の再起動が必要です。
   削除後に元に戻すには Re-deploy が必要になります。

「削除することに同意します」のチェックボックスにチェックを入れます。

(4) [🗑 削除する] ボタンをクリック

(5) 削除完了 → 再起動

カードから ✓ Installed バッジが消え、再起動バナーが表示されます。

7-2. 削除されるもの

[Remove] ボタンで削除されるのは以下のファイル・ディレクトリです：

対象	削除有無
`plugins/<id>.py`	✅ 削除
`plugins/<id>/` ディレクトリ全体（設定ファイル `<id>_config.ini` を含む）	✅ 削除
`data/index_cache.json`（インデックスキャッシュ）	❌ 残る
NAS 上のログ・出力ファイル	❌ 残る

NAS 上のデータは残ります: Plugin が NAS に保存したログ・録画・キャプチャ画像などは削除されません。必要に応じて NAS 側で手動削除してください。

8. 設定を変更する

freeBox Loader の設定は、Manager UI の Settings 画面から変更できます。Settings 画面で対応していない項目（ポート番号など）は、SSH 経由で freebox_config.ini を直接編集します。

8-1. Settings 画面で変更できる項目

サイドバーの Settings をクリックして表示される画面で、以下の項目を変更できます：

Loader セクション

項目	内容	初期値
Default Context	ルートアクセス（`/freebox/`）の転送先サブコンテキスト	`manager`
Index URL	GitHub からインデックス JSON を取得する URL	`https://raw.githubusercontent.com/hoscm/freebox/main/docs/index.json`

⚠ Default Context の変更について（v1 注意事項）: v1 では Default Context の変更を推奨しません。hsBox 管理画面の freeBox 連携リンク・タブが /freebox/manager/ を直指ししているため、変更すると hsBox 側からの導線が機能しなくなります。本件は v1.1.0 で改善予定です。

ℹ Index URL の変更について: Index URL は プラグイン開発者向けの設定です。通常運用では変更不要です。

Status Notification セクション

項目	内容	初期値
Notify URL	サービス起動時・異常終了時の通知送信先 URL	（空欄＝通知無効）

変更手順:

Settings タブを開く
各入力フィールドを編集
[保存] ボタンをクリック
「✓ 保存しました」と表示されれば完了
設定変更を反映するには freebox.service の再起動が必要です（後述 8-3）

[↺ リセット] ボタン: 編集内容を破棄して、現在保存されている値に戻します。保存していない場合のみ有効です。

8-2. SSH 経由で変更する項目（freebox_config.ini 直接編集）

⚠ メンテナンス用の設定です。 特に指示がある場合を除いて変更しないでください。誤った値を設定すると freeBox Loader が起動しなくなる可能性があります。

Settings 画面で対応していない項目は、SSH 経由で freebox_config.ini を直接編集して変更します。

対象項目（Settings UI に存在しない項目）:

セクション	項目	内容
`[server]`	`port`	Python HTTP サーバーの待受ポート番号（初期値 `9009`）
`[server]`	`host`	バインドアドレス（初期値 `127.0.0.1`、ループバックのみ）
`[server]`	`base_path`	Apache2 Proxy のベースパス（初期値 `/freebox`）
`[loader]`	`index_cache_ttl`	インデックスキャッシュ有効期限（秒、初期値 `3600`）
`[status]`	`notify_component`	通知時のコンポーネント名（初期値 `freebox`）
`[status]`	`nas_mount_point`	NAS マウントポイントのパス（初期値 `/mnt/nas`）

変更手順:

(1) hsBox に SSH でログイン

ssh hsbox@<hsBox の IP アドレス>
sudo su -

(2) 設定ファイルを編集

nano /home/hsbox/freebox/freebox_config.ini

(3) 保存して終了

Ctrl+O で保存、Ctrl+X で nano を終了します。

(4) サービスを再起動（後述 8-3）

設定ファイルの権限: freebox_config.ini は権限 640（他ユーザー読み取り不可）に設定されます。notify_url などに認証情報が含まれる可能性があるためです。編集後の権限変更は不要です（run.sh が自動設定します）。

8-3. 設定変更を反映させる（freebox.service の再起動）

Settings 画面・SSH 経由のいずれの方法で設定を変更しても、変更を反映するには freebox.service の再起動が必要です。

sudo systemctl restart freebox

再起動後、以下のコマンドで稼働確認できます：

sudo systemctl status freebox

Active: active (running) と表示されれば再起動成功です。

freeBox Loader 単体の再起動は v1 制限事項: Manager UI からの単体再起動 API は v1 では未実装です（v2 で対応予定）。SSH からの操作で対応してください。

9. アンインストール

freeBox Loader 自体を hsBox からアンインストールする場合は、SSH でログインして以下を実行します。

ℹ SSH ログイン手順について: 本手順は hsBox に SSH ログインできる前提で記載しています。SSH ログインの方法（ユーザー名・パスワード・接続方法等）は hsBox の利用者マニュアルを参照してください。

# hsBox に SSH でログイン
ssh hsbox@<hsBox の IP アドレス>
sudo su -

# サービスを停止・無効化する
systemctl stop freebox
systemctl disable freebox

# ファイルを削除する
rm -rf /home/hsbox/freebox
rm -f /etc/systemd/system/freebox.service
rm -f /etc/apache2/conf-enabled/freebox.conf
rm -rf /home/hsbox/www/freebox

# Apache2 を再起動して設定を反映
systemctl reload apache2
systemctl daemon-reload

NAS 上のデータは別途削除が必要: Plugin が NAS に保存したログ・キャプチャファイルは上記コマンドでは削除されません。必要に応じて NAS 側で手動削除してください。

10. よくある質問

10-1. Module の動作・再起動について

Q. インストール・削除後に必ず再起動が必要ですか？

A. はい。v1 では Plugin のホットロードに対応していません。

freeBox Loader v1 ではモジュールの追加・削除は freebox.service ではなく hsBox 全体の再起動が必要です。再起動はバナー表示の [🔄 今すぐ再起動] ボタン、または hsBox 管理画面のシステム設定から実行できます。

ホットロード対応は v2 で予定しています。

Q. Re-deploy（上書きインストール）はできますか？

A. v1 では Manager UI からの上書きインストールは制限されています。

既にインストール済みのモジュールに対して [Re-deploy] ボタンは v1 では非表示になっています。新しいバージョンに更新するには：

[Remove] で既存モジュールを削除
.hbx を再アップロード、またはインデックス経由で [Deploy]
hsBox を再起動

の手順で対応してください。Re-deploy 機能の再設計は v2 で予定しています。

Q. Deploy したらカードがすぐに更新されません

A. v1 では Deploy 後のカード自動更新に一部制限があります。

正常にインストールされても、ブラウザ側のキャッシュにより一覧が古い状態のままになる場合があります。[↺ Refresh Index] ボタンを押すか、ブラウザを再読み込み（F5）してください。

10-2. 同時利用・運用について

Q. 複数のブラウザタブで同時に Manager UI を開けますか？

A. v1 では 1 タブのみのご利用を推奨します。

複数タブからの同時操作には対応していません。複数タブを開いている状態で Deploy / Remove を実行すると、状態の不整合が生じる場合があります。常に 1 タブでご利用ください。

複数タブ管理は v2 で対応予定です。

Q. 同時に複数のモジュールを Deploy できますか？

A. v1 では Deploy 操作の排他制御は実装されていません。

UI 上は同時に複数の Deploy ボタンを押せますが、ファイル展開処理が競合する可能性があるため、1 つずつ順次実行することを推奨します。

排他制御は v2 で対応予定です。

10-3. NAS 関連

Q. StatusBar の NAS が `disconnected` と表示されています

A. NAS が hsBox にマウントされていないか、マウントされていても hsbox ユーザーが書き込みできない状態です。

freeBox Loader の NAS チェックは以下の 2 条件を満たすときのみ connected と判定します：

マウントポイント（初期値 /mnt/nas）が実際にマウントされている
hsbox ユーザーが書き込み権限を持っている

hsbox ユーザーで書き込みできるよう、NAS のマウントオプションで uid=$(id -u hsbox),gid=$(id -g hsbox) を指定してください（§2-6 参照）。

NAS が disconnected でも freeBox Loader 本体は正常に動作します。NAS 連携機能を持つモジュール（atomcam2 等）のみ動作に影響します。

Q. NAS なしで運用できますか？

A. はい、NAS なしでも freeBox Loader は動作します。

ただし、NAS への保存を必要とするモジュール（録画・キャプチャ系）は機能を制限されます。NAS を使わない場合は、それらのモジュールをインストールしないか、Plugin 側の設定でローカル保存に切り替えてください（モジュールごとの仕様に依存）。

10-4. オフライン環境

Q. インターネット接続なしで使えますか？

A. v1 では原則としてインターネット接続が必要です。

Manager UI は起動時に GitHub からインデックス JSON とアイコン素材を取得し、モジュールカードを表示します。インターネット接続がないと：

インデックス取得失敗 → 公開モジュール（public / restricted）の一覧が表示されません
既にインストール済みの private モジュールのみ動作します
アイコン取得失敗 → モジュールカード内のアイコンが ICON{0} のような文字列で表示される場合があります

オフライン環境での private モジュール運用改善は v2 で予定しています。

キャッシュ有効期間内は動作可能: 一度インデックスを取得した後、index_cache_ttl で指定された期間（初期値 1 時間）はキャッシュが利用されます。短時間のネットワーク断は問題になりません。

10-5. その他

Q. ログはどこに記録されますか？

A. systemd の journal に記録されます。

# 直近のログを確認
sudo journalctl -u freebox -n 100

# リアルタイムでログを追跡
sudo journalctl -u freebox -f

11. 次のステップ

ドキュメント	内容
`docs/specification.md`	freeBox の構成・アーキテクチャの詳細
`docs/module_dev_guide.md`	独自 Plugin モジュールの開発方法
`docs/hbx_build_tool_guide.md`	`.hbx` パッケージのビルド方法
`docs/loader_maintenance_guide.md`	Loader の運用・メンテナンス手順
`docs/run_sh_guide.md`	インストールスクリプト（`run.sh`）の実装方法

本ドキュメントは freeBox Loader v1.0.0 に基づきます。

This site is open source. Improve this page.