API ドキュメント

Town OS の systemcontroller API の完全なリファレンスです。アカウント、ストレージ、 リポジトリ、パッケージ、systemd、設定、監査、ページ、DNS、モニタリング、 システムサービス、ロケール、VM イメージ、ステータスにまたがる 77 個のエンドポイントを収録しています。

認証

ユーザー名とパスワードを添えて POST /account/authenticate を呼び出して 認証します。レスポンスには Bearer トークンが含まれるので、以降のリクエストに含めてください。

Authorization: Bearer <token>

セッションは 7 日間操作がないと期限切れになります。認証レベルは 5 種類あります。

パーティションの内部にあるエンドポイントは管理者に限られていませんが、オブジェクトストレージの パーティションを作ることだけは管理者に留保されています。パーティションは権限ツリーの根であり、 クォータ付きの btrfs サブボリュームを確保するからです。グラントが許すのはパーティションの中にいる 利用者を扱うことであって、そのパーティションが存在すべきかどうかを決めることではありません。

ステータス

ヘルスチェックとシステムの概要です。未認証の呼び出し元には status と needs_setup だけの最小限のレスポンスが返ります。認証済みの呼び出し元には、 ファイルシステム数、パッケージ数、ユニットの状態のまとめ、ディスク使用量、 外部・内部 IP、アップグレードの有無を含む、ダッシュボード用の完全なペイロードが返ります。

ストレージ

ファイルシステムを一覧します。ページ送りのパラメーターに加えて、リクエストボディで 任意の name（前方一致のフィルター）と state （user、installed、uninstalled）を受け付けます。

新しい btrfs のサブボリュームを作成します。name と、任意で quota（バイト）を送ります。クォータが 0 または未指定の場合は、 システムの既定値（50 GB）が使われます。予約された名前 （installed、uninstalled、archives）は拒否されます。

既存のファイルシステムを変更します。対象を特定するために name を送り、 更新後の name や quota を含む filesystem オブジェクトを渡します。

ファイルシステムを削除します。リクエストボディ: {"name": "mydata"}。

アーカイブをアップロードし、対象のサブボリュームへ展開します。subvolume の フィールドと archive のファイルを含む multipart/form-data を 受け付けます。対応形式は .tar.gz、.tgz、.tar.bz2、 .tbz2、.tar.xz、.txz、.tar、 .zip、.7z です。

サブボリュームの内容をアーカイブとしてダウンロードします。指定された形式で ストリーミングされたアーカイブを返します。

パッケージのボリュームをパッケージごとにまとめて一覧します。アンインストール済みの ボリュームを含めることもできます。

内部名を指定して、特定のパッケージのボリュームを削除します。

内部名を一つずつ指定して消していく代わりに、一つのパッケージに属するボリュームを 一度の呼び出しですべて削除します。

パッケージ

すべてのリポジトリにまたがって、利用できるパッケージを一覧します。各エントリーには リポジトリ、名前、バージョン、説明、supplies のタグ、インストール状況、 アップグレードの有無が含まれます。ページ送りのパラメーターに対応しています。

リポジトリごとにまとめてパッケージを一覧します。任意の search クエリ パラメーターを受け付けます。{"repo": "...", "packages": [...]} のグループの配列を返します。

インストール済みパッケージの識別子を一覧します。ページ送りのパラメーターに対応しています。

インストール済みパッケージの詳細情報を取得します。repo、name、 version を送ります。質問、利用者の回答、ノート、ノートの型を返します。

インストール済みパッケージについて保存された質問の回答を取得します。repo、 name、version を送ります。回答のキーと値のマップを返します。

パッケージの利用できるバージョンを一覧します。リクエストボディ: {"name": "nginx"}。 バージョン識別子の文字列配列を返します。

子パッケージを一覧します。repo と name を送ります。文字列の配列を返します。

パッケージのインストール時の質問を取得します。リクエストボディ: {"name": "nginx"}。 質問のキーと {"query": "...", "type": "..."} の対応を返します。

特定のバージョンのパッケージの質問を取得します。repo、name、 version を送ります。

oauth の質問について OAuth のデバイスフローを開始します。repo、 name、version、question を送ります。システム コントローラーがフローの開始ステップを提供元に対して実行し、flow_id、 approve_url（利用者のブラウザーで開きます）、任意の user_code、 そしてポーリングの間隔である interval_ms を返します。

提供元の URL は Town OS ではなくパッケージ側から来るものなので、呼び出す前に 検証されます。https のみで、ホスト自身のネットワーク上のアドレスは 決して許されません。

上で開始したフローをポーリングします。flow_id を送ります。 status を返し、利用者がまだ承認していなければ pending、 承認済みなら token とともに approved、フローがタイムアウトしたか トークンをすでに取得済みなら expired になります。フローは 1 回限りです。 取得したトークンは、入力された回答とまったく同じように、その質問の回答として /packages/install に送信します。

確定する前に、インストールで何が行われるかをプレビューします。repo、 name、version を送ります。ボリュームの詳細、ポートマッピング、 ディスク使用量、クォータの情報、アップグレード元のバージョン、そして人が読める 要約を返します。

パッケージをインストールします。

パッケージをアンインストールします。repo、name、 version と、関連データを削除する場合は任意の purge_volumes（boolean）を送ります。

インストール済みパッケージを無効にします（サービスを停止します）。repo と name を送ります。

無効にしたパッケージを再び有効にします（サービスを開始します）。repo と name を送ります。

インストール済みパッケージのデータボリュームをすべて削除します。repo と name を送ります。

以前のインストールから残ったボリュームがあるかを確認します。repo と name を送ります。has_uninstalled_volumes、 uninstalled_versions、installed_versions を返します。

以前アンインストールしたバージョンから残っているボリュームを削除します。 repo と name を送ります。

インストール済みパッケージで利用できるアップグレードを一覧します。各エントリーには installed_version、latest_version、そしてパッケージ定義が changed かどうかが含まれます。

現在のアップグレード通知を見送ります。空の JSON オブジェクトを送ります。

パッケージ定義の生の YAML を返します。repo、name、 version を送ります。ファイルの内容を Content-Type: text/x-yaml で返します。パッケージファイルが存在しない場合は 404 を返します。

すべてのリポジトリにまたがって、注目パッケージを一覧します。

パッケージについてキャッシュされた last の回答を取得します。repo と name を送ります。再インストール時に再利用するために、以前の アンインストール時に保存された回答を返します。

パッケージについてキャッシュされた last の回答のファイルを削除します。repo と name を送ります。

インストール済みパッケージの、git を元にしたボリュームの最新の変更を取得し、 依存するサービスを再起動します。repo、name、 version を送ります。再ビルドの前に、保存された回答に対して テンプレート変数が再評価されます。

設定

すべての設定をキーと値のオブジェクトとして取得します。

設定を 1 件取得します。リクエストボディ: {"key": "default_quota"}。 key と value を返します。

設定の値を変更します。リクエストボディ: {"key": "default_quota", "value": "107374182400"}。

既定の設定

ページ

3 種類のコンテンツソース（アーカイブのアップロード、コンテナーイメージ、git リポジトリ）に 対応した静的サイトのホスティングです。利用者がドメインを割り当てると、システムが Caddy のコンテナーを通じてコンテンツを配信します。変更を伴うエンドポイントはすべて 管理者としての認証が必要で、一覧のエンドポイントは通常の認証で利用できます。

すべてのページを、並べ替え、検索、ページ送りとともに一覧します。名前、リポジトリの URL、 ブランチ、ドメイン、ソースの種類、状態、タイムスタンプで並べ替えられます。

新しいページを作成します。名前、ソースの種類（archive、 container_image、git）、リポジトリの URL、ブランチ、ドメイン、 コンテナーイメージ、イメージ内のディレクトリを受け付けます。ソースの種類の既定値は archive です。git とコンテナーイメージのページは非同期に プロビジョニングされます。

アーカイブ形式のページ向けに、コンテンツの tar アーカイブをアップロードします。 name と archive のファイルを含むマルチパートフォームを 受け付けます。ソースの種類が archive のページでのみ有効で、それ以外の 種類では 400 を返します。

ページのリポジトリ URL、ブランチ、ドメイン、ソースの種類、コンテナーイメージ、 イメージ内のディレクトリを部分的に更新します。指定したフィールドだけが変更されます。

データベースからページを削除し、webroot のシンボリックリンクを外して、btrfs の サブボリュームを削除します。

ページのコンテンツをソースから再ビルドします。git のページは最新の変更を取得し、 コンテナーイメージのページはイメージから取り出し直します。アーカイブのページは 400 を返します（代わりに /pages/upload で再アップロードしてください）。

ネットワーク

ネットワークとは、名前を持つ WireGuard オーバーレイと DNS の TLD を 組み合わせたものです。パッケージはネットワークにインストールされ、ピアはそこに参加し、 誰が何を解決できるかを分けるのが TLD です。ネットワーク名は DNS ラベルとして安全な形式で、 32 文字までに制限されています。WireGuard のインターフェース接尾辞と systemd の ユニット名にそのまま使い回されるからです。

home ネットワークは常に存在します。起動時に作られるのではなく、データベースそのものと 一緒に植え付けられます。そして三つの点で特別です。削除できず、二度目を作ることも できません。DNS 専用です（WireGuard のインターフェースもサブネットもピアも ありません）。そしてピアの登録は 400 で拒否されます。すべてのアカウントは home ネットワークに属しているので、ここで登録を受け付ければ、所属しているというだけで トンネルへの入口になってしまい、しかも保存されたピアは存在しないトンネルを記述することになります。

ネットワークを無効にすると止まるのは伝送路だけです。WireGuard のインターフェースが 立ち上がらなくなるのでリモートからの接続は切れますが、ローカルの DNS 解決とコンテナー自体は 動き続けます。

ネットワークを一覧します。各エントリーには、名前、TLD、サブネット、オーバーレイ上での この機器自身のアドレス、公開鍵、待ち受けポート、有効フラグが入ります。秘密鍵が シリアライズされることはありません。

ネットワークを作成します。サブネットは、機器の識別情報のシードとネットワーク名から決定的に 導かれ、家庭用ルーターが配りがちな範囲を避けるために 10.64.0.0/10 から取られます。 機器の識別情報を鍵にしているので、ピアを受け入れる Town OS の機器が 2 台あっても別々の サブネットを選び、両方に参加する端末が衝突を見ることはありません。home を作ろうと すると、TLD の衝突チェックによって 409 が返ります。

ネットワークを削除します。home ネットワークは拒否されます。

そのネットワークの WireGuard の伝送路を立ち上げます。

DNS とコンテナーを動かしたまま、伝送路だけを止めます。

ピア

あるネットワークに登録されているピアを一覧します。

登録されているだけでなく、実際に今つながっているピアを一覧します。

ピアを登録します。管理者でない利用者を通すのは wireguard のグラントで、ネットワークごとの 範囲と各ピアの所有関係はハンドラーが確認します。home ネットワークは DNS 専用なので 400 が返ります。

ピアの登録を TTL が切れる前に更新します。登録には期限があり、期限切れになったものは 回収する仕組みが取り除きます。

ピアをネットワークから取り除きます。

ローカル CA

この機器のローカル認証局を PEM 形式でダウンロードします。Town OS はパッケージの名前に対して 自前の証明書を発行するので、この証明書を信頼することが、それらの名前をブラウザーで警告なしに 使えるようにする鍵になります。公開されているのは意図的です。CA 証明書は配布するためのもので あり、クライアントは認証に使える資格情報を持つより前にこれを必要とするからです。

モニタリング

システム監視のために統合された Prometheus、Node Exporter、Grafana のスタックです。 スタックは Restart=always を設定した、systemd 管理下の podman コンテナーとして動作します。

監視サービスごとにコンテナーの状態（名前、イメージ、稼働状態、ポート）を返します。 監視が構成されていない場合は {"status": "disabled"} を返します。

ダッシュボードのデータへの到達方法

システムコントローラーを通るリバースプロキシは存在しません。 監視データは専用のポート 5308 で提供され、ブラウザーはそのポートと直接やり取りします。 コントローラー自身のポート（5309）が担うのは /monitoring/status だけです。 5308 で何が待ち受けるかは、構成されたバックエンドによって決まります。

• uPlot モード（既定）—— socat のフォワーダーが Prometheus の HTTP API を 5308 に出し、UI は /api/v1/query_range を直接問い合わせて、自分でグラフを描きます。
• Grafana モード—— podman のポートマッピングによって Grafana が 5308 で直接待ち受け、 UI はそれを iframe に埋め込みます。

TOWN_OS_MONITORING_PORT はダッシュボードのポートを移動させ、 TOWN_OS_PROMETHEUS_PORT と TOWN_OS_NODE_EXPORTER_PORT は 二つのループバックのポートに対して同じ働きをします。

ロケール

システムの国際化に関するロケールの情報です。

現在のロケール、翻訳が用意されているロケールの一覧、主要な言語（それぞれの文字での 名称つき）、拡張ロケールを返します。BCP 47 のロケールコードを使います。

オブジェクトストレージ管理 API（gfeh）

ここまではすべて Town OS の API で、アプリケーションが普段使うべきものはそちらです。その下で、 各 gfehd パーティションは独自の管理面を持っています。JSON over HTTP ですが、 その Unix ソケットの上だけで提供され、ポートで待ち受けることはありません。

この面にはトークンも認証もありません。ソケットに対するファイルシステムの パーミッションそのものがアクセス制御であり、そこへ到達できる時点で、その機器の root であることを意味します。ソケットが btrfs のボリュームの上にあるのは、 gfehd のコンテナーとシステムコントローラーのコンテナーの双方から見える 唯一のファイルシステムがそこだからです。

gfehd は内部のエラーを HTTP のステータスコード（404、409、400）に対応付け、 Go のクライアントがそれをセンチネルエラーへ戻します。おかげで errors.Is が ソケットの境界をまたいでも機能します。

<network> という名前のネットワークについて、パーティションのファイルの置き場所は次のとおりです。

クライアントライブラリ

Town OS には、API を完全に網羅した Go と JavaScript のクライアントライブラリが 同梱されています。どちらのクライアントも、200 以外のレスポンスに対して RFC 9457 の problem detail を使った型付きのエラーを送出します。

Go クライアント

Go クライアントは src/svc/systemcontroller/client.go にあり、 Client インターフェースを実装しています。Unix ソケットと HTTP の どちらの接続にも対応します。

// Connect via Unix domain socket (production)
client := systemcontroller.InitClient("/run/town-os/systemcontroller.sock")

// Connect via HTTP (development / testing)
client := systemcontroller.FromClient(http.DefaultClient, "http://localhost:5309")

認証後は client.Token を設定してください。すべてのメソッドは、 第 1 引数に context.Context を取ります。

ストレージ

リポジトリ

パッケージ

systemd

アカウント

監査・設定・アップグレード

アーカイブ

ヘルス

開発リファレンス

Town OS のバックエンドはポート 5309 で動作し、Vite の開発サーバーはポート 5173 で動きます。 開発環境一式を起動するには make dev を使ってください。

主要なターゲット

テスト用のターゲット

ビルド用のターゲット