workspaceguard

WorkspaceGuard

インストール • クイックスタート • CLI リファレンス • 比較 • FAQ

1 つの共有セルフホスト型 AI アシスタント環境（Odysseus または互換バックエンド）を対象に、ワークスペースごとの使用量を計測し、上限に達したら確実に遮断するクォータ上限を設定できます。

ご家庭や小規模チームで Odysseus（または互換性のあるセルフホスト型アシスタント）を実行していると、今月誰が何件メッセージを送ったか確認する方法も、1人の使用量が全員の API 予算を使い果たすのを防ぐ方法もありません。WorkspaceGuard は、ワークスペースごとのメッセージ数、確実に遮断するオプションの月間上限、そして管理者や別のエージェントが読み取れる CLI（または JSON）レポートを追加するサイドカーです。

npx workspaceguard-cli usage
-> alex   [[email protected]]: 812 messages this period, cap 1000 (81%)
-> jordan [[email protected]]: 203 messages this period, cap unlimited

インストール

npm install -g workspaceguard-cli

インストールせずに実行することもできます。

npx workspaceguard-cli usage

パッケージ名は workspaceguard-cli で、インストールされるコマンドは workspaceguard です。同じ CLI インターフェイスと --json の形式を備えた、独立して開発された真正な Python 移植版は、PyPI で workspaceguard-cli として別途公開されています（pip install workspaceguard-cli。詳細は python/ を参照してください）。

クイックスタート

# Register the workspaces sharing one deployment (identity = the header value
# your reverse proxy sets after authenticating, e.g. Cloudflare Access).
workspaceguard add-workspace alex --identity [email protected]
workspaceguard add-workspace jordan --identity [email protected]

# Optional: cap alex at 1000 messages/month. Omit for unlimited (the default).
workspaceguard set-cap alex 1000

# See usage for every workspace.
workspaceguard usage

新規インストール時の実際の出力：

-> alex [[email protected]]: 0 messages this period, cap 1000 (0%)
-> jordan [[email protected]]: 0 messages this period, cap unlimited

機能

• ワークスペースごとのメッセージ数の計測。 サイドカーの chat() エントリーポイントを通過するすべてのリクエストで、ワークスペースごと、月ごとのカウンター（src/core/usage.ts）が増加します。ワークスペース間で使用量が漏れることはありません。
• 確実に遮断するクォータ適用。 上限に達したワークスペースでは、バックエンドを呼び出す前に QuotaExceededError が発生します。使用量ストアが破損している、または読み取れない場合、WorkspaceGuard は全員のカウントを暗黙にゼロへリセットするのではなく、リクエストをブロックします（CHANGELOG.md を参照）。
• すべてのコマンドでエージェント対応の --json を利用可能。 workspaceguard usage --json は、スクリーン上の出力を解析することなく、オーケストレーターが直接解析できる構造化データを返します。
• 実際にキーをローテーションできる AES-256-GCM ボールト。 workspaceguard rotate-key <id> は、ワークスペースのシークレットを新しいキーで再暗号化し、古い暗号文を無効にします。
• 自己修復型サーキットブレーカー。 バックエンドの呼び出しが連続して3回失敗すると回路が開き、その後は半開状態のプローブで再試行します。成功すると回路は閉じるため、トリップ状態のままになりません。
• チェックをあちこちに散らさず、単一の要所に集約。 src/core/isolation-guard.ts の chat() が、すべてのリクエストが通る唯一の場所です。ワークスペースを特定し、クォータを確認し、バックエンドを呼び出し、使用量を記録します。
• 独立した2つのテスト済み配布版。 TypeScript パッケージ（npm）と Python 移植版（PyPI）は、個別のテストスイートで同じ設計を実装しています。この記事の執筆時点で、TypeScript のテストは41件中41件、Python のテストは50件中50件に合格しています。

CLI リファレンス

すべてのコマンドで --json を指定すると、以下に示す人間が読みやすいテキストではなく、構造化されたエージェントネイティブな形式で出力されます。

コマンド	動作
workspaceguard init	このデプロイ用のデータディレクトリとボールトを初期化します。
workspaceguard add-workspace <id> --identity <value>	ワークスペースを登録します。同じ ID に対する繰り返しの呼び出しは冪等です。--identity は位置引数として解析され、<id> の直後に指定する必要があります。独立したフラグとしては指定できません。
workspaceguard status [--json]	設定済みのワークスペースを一覧表示します。
workspaceguard usage [--json]	今月のワークスペースごとのメッセージ数、上限、使用率を表示します。
workspaceguard set-cap <id> <count|none>	ワークスペースの月間メッセージ上限を設定または解除します。
workspaceguard rotate-key <id>	ワークスペースのボールト暗号化キーをローテーションします（古い暗号文は無効になります）。
workspaceguard scan [--json]	隔離設定のスキャンです（元のビルドから引き継いだスキャフォールドのスタブで、現在は常に空の検出結果リストを返します）。
workspaceguard -h、--help	上記のコマンド一覧を表示して、0 で終了します。
workspaceguard -V、--version	インストール済みパッケージのバージョンを表示して、0 で終了します。

グローバルオプション

オプション	動作
--data-dir <path>	設定、ボールト、使用状況データのデータディレクトリです。WORKSPACEGUARD_DATA_DIR より優先されます。
--force	init 専用：解決されたデータディレクトリにある既存のキーファイルが破損または切り詰められているように見える場合でも、マスターキーを再生成します。
--json	人間が読みやすいテキストではなく、構造化されたエージェントネイティブな形式で出力します。

警告

--force を指定すると、古いマスターキーで暗号化されたデータはすべて永久に無効になります。既存のキーファイルが復元不能であることを確認できた場合にのみ使用してください。

データディレクトリの解決順序： --data-dir フラグ、WORKSPACEGUARD_DATA_DIR 環境変数、~/.workspaceguard の順です。以前は、上書き指定がない場合、現在の作業ディレクトリがデフォルトでした。誤ったシェルから init を実行すると、稼働中の暗号化キーが無関係なディレクトリに気付かないまま書き込まれる可能性がありました。有効なキーがすでに存在する場合、init は冪等であり、そのキーを読み込んで再利用します。キーファイルが存在していても有効なキーとしてデコードできない場合、--force を指定しない限り上書きを拒否します。

$ workspaceguard usage --json
{"ok":true,"usage":[{"workspaceId":"alex","identity":"[email protected]","monthlyMessageCap":1000,"percentUsed":81,"period":"2026-07","messageCount":812,"estimatedBytes":48213}]}

--json モードによって、人間にとって便利なだけでなく、エージェントネイティブなものになります。オーケストレーターや監視エージェントは workspaceguard usage --json を呼び出して結果を直接解析でき、ターミナル出力をスクレイピングする必要はありません。

ライブラリ API

import { createWorkspaceGuard, MockAdapter, QuotaExceededError } from "workspaceguard-cli";

const guard = await createWorkspaceGuard({ dataDir: "./data", backend: new MockAdapter() });
await guard.addWorkspace("alex", "[email protected]");
await guard.setCap("alex", 1000);

try {
  await guard.chat("[email protected]", "hello");
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // alex is over their monthly cap
  }
}

const report = await guard.usageReport();

Python 版も同じ形式を公開しています：from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError。

MCP サーバー

WorkspaceGuard の Python ディストリビューションには、Model Context Protocol サーバーが含まれています。そのため、MCP 対応エージェント（Claude Desktop、Claude Code、オーケストレーター）は、CLI にシェルアウトしてテキストを解析する代わりに、WorkspaceGuard をツールとして直接呼び出せます。

pip install "workspaceguard-cli[mcp]"

公開するツールは run の1つで、汎用的なサブプロセスラッパーです。コマンドラインで指定するものと同じ引数リストを渡すと、インストール済みの workspaceguard バイナリをシェルから実行し、結果の JSON を解析して返します。バイナリの欠落、起動エラー、タイムアウト、ゼロ以外の終了コード、解析できない出力など、すべての失敗ケースは例外を送出せず、単純な {"error": ...} 辞書として返されるため、不正な呼び出しでサーバーがクラッシュすることはありません。

run(args=["usage", "--json"])
# -> {"ok": true, "usage": [{"workspaceId": "alex", "identity": "[email protected]", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-08", "messageCount": 0, "estimatedBytes": 0}]}

Claude Desktop などの MCP 対応クライアントに登録するには、クライアントのサーバー設定に追加します。

{
  "mcpServers": {
    "workspaceguard": {
      "command": "workspaceguard-mcp"
    }
  }
}

これは、workspaceguard-mcp がすでに PATH 上にあること（上記の mcp エクストラを使ってインストール済みであること）を前提としています。別の場所にインストールした場合は、"command" をコンソールスクリプトのフルパスに置き換えてください。

比較

WorkspaceGuard は競合製品ではなく、サイドカーです。Odysseus のデプロイメント（または互換性のあるバックエンド）の前段に配置し、バックエンドが提供していないレイヤーを追加します。

機能	WorkspaceGuard	Odysseus（標準機能）
ユーザーごとの分離（チャット履歴、メモリ、API キー）	再実装せず、すでに解決済みのものとして扱います	はい、デフォルトで組み込み済みです
ワークスペースごとのメッセージ数カウント	はい	いいえ
月間クォータ上限、フェイルクローズ	はい	いいえ
CLI / --json 使用状況レポート	はい	いいえ
ライセンス	MIT	AGPL-3.0

WorkspaceGuard とは何か、なぜ存在するのか

このプロジェクトは当初、セルフホスト型の AI チャットプラットフォームに、ユーザーごとのワークスペース分離（チャット履歴、メモリ、API キーの分離）を追加することを目指していました。実現可能性の検証により、Odysseus はデフォルトでチャット履歴、メモリ、API トークンのユーザーごとの所有権をすでに適用していることが分かったため、競合する分離レイヤーを構築すると、Odysseus がすでに正しく実現している機能を重複して実装することになります。

そこで WorkspaceGuard は、テスト済みの分離エンジン（名前空間の分離、実際のキーのローテーションに対応した AES-256-GCM ボールト、フェイルクローズ型の ID 解決、自己修復型のサーキットブレーカー）を ID 解決の基盤として維持し、Odysseus が提供していないレイヤーである、ワークスペースごとの使用量計測とクォータ適用を構築します。

無料プラン（このリポジトリ、MIT）： ワークスペースごとのメッセージ数カウント、月間上限の適用、CLI/JSON 使用状況レポート。このリポジトリに含まれないもの： ホスト型のマルチテナント課金ダッシュボードは別のクローズドソース製品です。ここではロードマップ項目としてのみ言及しており、この MIT コードベースにマージされることはありません。

アーキテクチャ

• src/core/isolation-guard.ts -- すべてのリクエストが通過する単一の要所（chat()）です。ワークスペースを解決し、クォータを確認して、バックエンドを呼び出し、使用量を記録します。
• src/core/usage.ts -- このプロジェクトが追加する使用量計測エンジンです。ワークスペースごと、月ごとのカウンター、自動的な期間更新、QuotaExceededError による適用を備えています。
• src/core/vault.ts、src/core/namespace.ts、src/core/circuit-breaker.ts -- 元の分離エンジンのコードです。計測レイヤーが参照する ID とワークスペース境界の基盤として維持されています。
• src/adapters/ -- BackendAdapter インターフェースです。現時点で唯一の実装は MockAdapter です。実際の Odysseus HTTP アダプターはまだ構築されていません。

バックエンド固有の動作が src/core/ に直接入ることはありません。すべて BackendAdapter を経由します。

信頼境界

WorkspaceGuard は、ワークスペースの解決に上流の ID ヘッダー（デフォルト：Cf-Access-Authenticated-User-Email）を信頼します。

警告

このサービスにネットワークから直接アクセスできる状態にしてはいけません。このヘッダーを設定する信頼できるプロキシ（Cloudflare Access、Tailscale など）の背後でのみ実行してください。この境界は文書化されていますが、コードでは強制されません。

実装済みの機能と未実装の機能

• 実装済みでテスト済み： 使用量計測、クォータ適用、元の分離エンジン（ボールト、名前空間の分離、サーキットブレーカー）、および --json モード対応 CLI。TypeScript テスト 41/41 件、Python テスト 50/50 件の合格により検証済みです。
• 未実装： 実際の Odysseus HTTP アダプター（現時点では MockAdapter のみ）と、ホスト型のマルチテナント課金ダッシュボード（この MIT リポジトリでは意図的に対象外です）。

ドキュメント

• docs/getting-started.md
• docs/concepts.md
• docs/integrations/ci.md
• docs/integrations/backends.md

FAQ

Q: WorkspaceGuard は実際に何をするものですか？ A: 1 つの共有セルフホスト型 AI アシスタントのデプロイメントの前段で、ワークスペースごとの使用量の計測とクォータの適用を行います。ワークスペースごとに月単位でメッセージ数をカウントし、任意の上限を設定できます。上限に達すると、それ以降のリクエストは拒否されます。また、あなたやエージェントが workspaceguard usage レポートを確認できます。チャット履歴、メモリ、API キーの分離機能は追加しません。これらは対象プラットフォームでデフォルトで提供されています（上記の「WorkspaceGuard とは」を参照してください）。WorkspaceGuard 自身の分離コード（src/core/vault.ts、src/core/namespace.ts）は、計測レイヤーが参照する ID 解決の基盤としてのみ残されています。

Q: WorkspaceGuard の実際の差別化要因は何ですか？ A: 範囲を絞り、確実に実現していることです。フル機能の課金プラットフォームではなく、バックエンドがすでに備えている分離機能を再実装するものでもありません。すべてのリクエストは 1 つの要所（src/core/isolation-guard.ts の chat()）を通ります。使用量ストアが破損している場合、クォータの適用は全員の使用量を黙ってゼロにリセットするのではなく、リクエストを拒否します（CHANGELOG.md を参照してください）。また、すべてのコマンドがエージェント向けの出力に使える --json をサポートしています。

Q: WorkspaceGuard は Odysseus とどう違いますか？ A: 競合製品ではありません。WorkspaceGuard は Odysseus のデプロイメント（または互換性のあるバックエンド）の前段に置くサイドカーであり、Odysseus がすでに提供している機能を置き換えるものではありません。機能の具体的な分担については、上記の比較表を参照してください。

Q: WorkspaceGuard はどのプラットフォームで動作しますか？ A: npm パッケージ（workspaceguard-cli）の要件は Node.js 20 以降です（package.json の engines.node を参照してください）。Python 版（python/）の要件は Python 3.9～3.13 です（python/pyproject.toml の分類子を参照してください）。どちらの配布物にもプラットフォーム固有のバイナリは含まれていないため、それぞれのランタイムが動作する環境（Linux、macOS、Windows）で実行できます。

Q: WorkspaceGuard は CLI、ライブラリ、それとも両方ですか？ A: どちらの配布物も両方を提供しています。CLI（workspaceguard <command>）では、init、add-workspace、status、usage、set-cap、rotate-key、scan を利用できます。同じ機能は直接インポートして使用することもできます（TypeScript パッケージの createWorkspaceGuard、Python パッケージの create_workspace_guard）。シェルからコマンドを実行する代わりに、コードから呼び出したい場合に利用できます。

Q: 利用を決める前に知っておくべき、現在の実際の制限は何ですか？ A: 現在実装されているバックエンドアダプターは、テストやローカルでの試用に使うメモリー内アダプターの MockAdapter のみです。実際の Odysseus HTTP アダプターはまだ構築されていないため（docs/integrations/backends.md を参照してください）、WorkspaceGuard は実際の Odysseus デプロイメントにライブチャットのトラフィックをまだ転送できません。計測とクォータのロジック自体は実装済みで、テストもされています。まだ残っているのは、実際のバックエンドへのネットワーク接続部分です。

Q: WorkspaceGuard 独自の API キーは必要ですか？AI プロバイダーの認証情報を保持しますか？ A: いいえ。現在存在する唯一のバックエンドアダプター（MockAdapter）はメモリー内で動作し、外部 API を呼び出しません。バックエンド固有の動作はすべて BackendAdapter インターフェース（src/adapters/）の背後に隔離されているため、WorkspaceGuard 自身のコードがプロバイダーの認証情報を直接参照することはありません。

Q: WorkspaceGuard は商用利用できますか？ A: はい。このリポジトリ全体は MIT ライセンスで提供され、デュアルライセンスや機能制限はありません。前述のホステッド型マルチテナント課金ダッシュボードは別のクローズドソース製品で、ロードマップ項目としてのみ記載されています。この MIT コードベースには課金ダッシュボードのコードは含まれておらず、非公開にされているものもありません。

コントリビューションとセキュリティ

CONTRIBUTING.md と SECURITY.md を参照してください。重要な変更は CHANGELOG.md に記録されています。

ライセンス

MIT。