Platter

platter

コンピューターを、すぐ使える形で。

Stdio および StreamableHTTP トランスポート経由で Read、Write、Edit、Bash、Glob、Grep、JS ツールを提供する MCP サーバーです。Bun で構築され、スタンドアロン実行ファイルにコンパイルできます。

Hadrian のようなブラウザー上で動作する（または MCP 互換の）エージェントが、コンピューターを操作するために使用することを想定しています。

ツール

ツール	説明
read	ページネーション（offset/limit）に対応してファイルの内容を読み取ります。画像ファイル（JPEG、PNG、GIF、WebP）を検出し、メタデータを返します。テキストは 2000 行または 50KB で切り詰められます。
write	ファイルを作成または上書きします。親ディレクトリは自動作成されます。
edit	完全一致またはあいまい一致で検索・置換します（スマートクォート、ダッシュ、Unicode の空白を正規化します）。一致箇所は一意である必要があります。すべての出現箇所を置換するには replace_all を使用してください（完全一致のみ）。統合 diff を返します。
bash	オプションのタイムアウト付きでシェルコマンドを実行します。出力は最後の 2000 行または 50KB で切り詰められます。
glob	ファイルパターンを高速に照合します。glob パターン（例：**/*.ts）に一致するパスを最大 500 件返します。
grep	ripgrep を使ってファイルの内容を検索します。正規表現、ファイルのフィルタリング、前後のコンテキスト行、複数の出力モードに対応しています。rg のインストールが必要です。
js	永続的な Node.js vm コンテキストで JavaScript/TypeScript を評価します。セッション内の呼び出し間で状態が保持されます。await、console.log、await load("package") による unpkg.com からのパッケージ読み込みに対応しています。最後の式を自動的に返します。セキュリティサンドボックスではありません — 下記のセキュリティを参照してください。

クイックスタート

リリースバイナリから

Releases からお使いのプラットフォーム向けの最新バイナリをダウンロードするか、curl で取得してください。

# Download (replace the filename for your platform)
# Available: platter-linux-x64, platter-linux-arm64, platter-darwin-x64, platter-darwin-arm64
curl -fsSL https://github.com/hadriangateway/platter/releases/latest/download/platter-linux-x64 -o platter
chmod +x platter

./platter          # stdio mode
./platter -t http  # HTTP mode on :3100

Docker

docker run --rm -i ghcr.io/hadriangateway/platter                                   # stdio mode
docker run --rm -p 3100:3100 ghcr.io/hadriangateway/platter -t http --host 0.0.0.0  # HTTP mode

パスのマウント、ネットワーク、追加ソフトウェアのインストール、カスタムイメージのビルドについては、下記の Docker を参照してください。

ソースから

bun install
bun run dev      # run directly from TypeScript
bun run compile  # build standalone binary for current platform

使い方

platter v1.x.x

Your computer, served on a platter.

Usage: platter [options]

Options:
  -t, --transport <stdio|http>   Transport mode (default: stdio)
      --tray                     Run the HTTP server with a Linux system tray
                                 (implies --transport=http, persists state
                                 across restarts in ~/.config/platter)
  -p, --port <number>            HTTP port (default: 3100)
      --host <address>           HTTP bind address (default: 127.0.0.1)
      --cwd <path>               Working directory for tools (default: current directory)
      --cors-origin <origin>     Allowed CORS origin (default: *)
      --auth <mode>              Auth mode: oauth, bearer, jwks, none (default: oauth)
      --auth-token <token>       Bearer token for HTTP auth (auto-generated if omitted)
      --tls-cert <path>          TLS certificate file (PEM) — enables HTTPS
      --tls-key <path>           TLS private key file (PEM)

External JWKS / OIDC (--auth jwks — verify tokens from an external IdP):
      --oauth-issuer <url>       Issuer URL; OIDC-discovers the JWKS endpoint
      --jwks-url <url>           Explicit JWKS endpoint (overrides discovery)
      --oauth-audience <aud>     Expected token audience (strongly recommended)
      --jwks-scope-grants        Map tools:<name> token scopes to tool access
                                 (fail closed: a token with no tools:<name>
                                 scopes is granted no tools)

Process management:
      --max-processes <number>   Max concurrent bash processes per session (default: 20)
      --max-sessions <number>    Max concurrent HTTP sessions (default: unlimited)

Restrictions:
      --tools <list>             Comma-separated tools to enable (default: all)
                                 Valid: read, write, edit, bash, glob, grep, js
      --allow-path <path>        Restrict read/write/edit/glob/grep to this path (repeatable)
                                 Does not restrict bash or js
      --allow-command <regex>    Allow bash commands matching this pattern (repeatable)
                                 Pattern must match the entire command string
                                 Applies to bash only; does not restrict js

Sandbox (applies to bash only; the js tool is never sandboxed):
      --sandbox                  Use just-bash sandbox instead of native bash
      --sandbox-fs <mode>        Filesystem backend: memory, overlay, readwrite (default: readwrite)
      --sandbox-allow-url <url>  Allow network access to URL prefix (repeatable)

  -h, --help                     Show this help message
  -v, --version                  Show version number

制限

登録するツール、ファイルツールがアクセスできるファイルシステムのパス、bash ツールが実行できるコマンドを制限できます。

ツールの選択

特定のツールのみを登録します。登録されていないツールは MCP クライアントから完全に隠されます。

platter --tools read,glob,grep    # read-only server
platter --tools read,write,edit   # no bash/search/js

パスの制限

ファイルにアクセスするツール（read、write、edit、glob、grep）がアクセスできるディレクトリツリーを 1 つ以上に制限します。パスは絶対パスに変換され、範囲外へのアクセスを防ぐためにシンボリックリンクも realpath で解決されます。

platter --allow-path /home/user/project
platter --allow-path /home/user/project --allow-path /tmp

コマンドの制限

コマンド文字列全体が少なくとも 1 つの正規表現パターンに一致する bash コマンドのみを許可します。

platter --allow-command "git( .*)?"                             # git only
platter --allow-command "git( .*)?" --allow-command "npm( .*)?" # git or npm
platter --allow-command "ls( .*)?" --allow-command "cat .*"     # ls or cat

パターンはアンカー付きです。--allow-command "git( .*)?" は ^(?:git( .*)?)$ にコンパイルされるため、git status は一致しますが、rm -rf / && git status は一致しません。

組み合わせの例

# Locked-down: read-only tools, scoped to one directory
platter --tools read,glob,grep --allow-path /home/user/project

# Full tools, but bash restricted to git/npm, files restricted to project
platter --allow-path ./my-project --allow-command "git( .*)?" --allow-command "npm( .*)?"

有効な制限は起動時に stderr に記録されます。

認証

--auth <mode> で制御します。

モード	説明
oauth（デフォルト）	OAuth 2.1 Authorization Code + PKCE。フォールバックとして静的ベアラートークンを使用します
bearer	静的ベアラートークンのみ
jwks	リソースサーバーモード：JWKS を介して外部 OAuth/OIDC 発行者（Auth0、Keycloak、Okta、Entra）が発行した JWT アクセストークンを検証します
none	認証なし

OAuth 2.1 (--auth oauth)

RFC 9728（Protected Resource Metadata）に対応する MCP クライアントは、platter の OAuth エンドポイントを自動的に検出し、トークンを手動でコピーせずに認証できます。

フロー：

1. クライアントが /.well-known/oauth-authorization-server と /.well-known/oauth-protected-resource/mcp を検出します
2. クライアントが POST /register を使って登録します（RFC 7591 の動的クライアント登録）
3. クライアントが /authorize を使って Authorization Code + PKCE フローを開始します
4. 確認コードが別経路で表示されます（stderr に出力されるか、トレイモードではデスクトップ通知として表示されます）
5. ユーザーが同意ページを確認し、確認コードを入力して、許可するツールを選択し、リクエストを承認または拒否します
6. クライアントが /token で認可コードをトークンと交換します
7. 以降のリクエストでは Authorization: Bearer <access_token> を使用します

確認コードによって、リクエストを承認する人が platter プロセスにアクセスできることを証明します。同意ページにアクセスできるリモート攻撃者も、確認コードがなければ承認できません。コードは1回のみ使用でき、有効期限は5分で、試行回数は最大5回です。

アクセストークンの有効期限は1時間で、更新できます。クライアント登録情報は ~/.config/platter/clients.json に保存されます。OAuth に対応していないクライアント向けのフォールバックとして、静的なベアラートークンも使用できます。

ベアラートークン（--auth bearer）

ランダムなベアラートークンが起動時に生成され、stderr に出力されます（トレイモードではシステムのキーリングに保存されます）。すべてのリクエストに Authorization: Bearer <token> を含める必要があります。独自のトークンも指定できます：

platter -t http --auth bearer --auth-token my-secret-token

認証なし（--auth none）

認証を完全に無効にします（例：認証を処理するリバースプロキシの背後で使用する場合）：

platter -t http --auth none

外部 JWKS / OIDC（--auth jwks）

jwks モードでは、platter は純粋なリソースサーバーとして動作し、独自のトークンは発行しません。代わりに、外部の OAuth/OIDC 認可サーバー（Auth0、Keycloak、Okta、Microsoft Entra）が発行した JWT アクセストークンを検証します。発行者の JWKS に対する署名の検証に加え、iss、aud、exp クレームも検証します。これにより、リバースプロキシを使わずに、既存の IdP の背後に platter を配置できます。

# Auth0 (root issuer)
platter -t http --auth jwks \
  --oauth-issuer https://YOUR_TENANT.auth0.com/ \
  --oauth-audience https://platter.example.com/mcp

# Keycloak (realm issuer)
platter -t http --auth jwks \
  --oauth-issuer https://kc.example.com/realms/myrealm \
  --oauth-audience platter-api

# Skip discovery / point at a JWKS endpoint directly
platter -t http --auth jwks \
  --jwks-url https://idp.example.com/.well-known/jwks.json \
  --oauth-audience platter-api

オーディエンスの検証（強く推奨）。 IdP で設定した API 識別子を --oauth-audience に指定してください。省略すると、platter は発行者からの有効なトークンをすべて受け入れます。これには、別のリソースサーバー向けに発行されたトークンも含まれるため、混乱した代理人のリスクがあります。オーディエンスの検証が無効な場合、platter は起動時に警告を出力します。

ディスカバリー。 --oauth-issuer を指定すると、platter は起動時に発行者の /.well-known/openid-configuration（取得できない場合は /.well-known/oauth-authorization-server）を取得し、jwks_uri を見つけるとともに、RFC 9728 対応の MCP クライアント向けに認可サーバーの情報を再公開します（/.well-known/oauth-protected-resource/mcp）。ディスカバリーを省略する場合、または起動時に IdP に到達できない場合は、--jwks-url を指定してください。ディスカバリーに失敗しても --jwks-url が設定されていれば、トークン検証は引き続き機能します。その場合、RFC 9728 による自動公開のみがスキップされます。

認可（トークンでできること）。 デフォルトでは、検証済みトークンには管理者レベルのアクセス権が付与され、その範囲はオペレーターの CLI による制限（--tools、--allow-path、--allow-command、--sandbox）のみで制限されます。つまり、IdP は誰がアクセスできるかを制御し、CLI フラグは何ができるかを制御します。トークン内の tools:<name> スコープ（例：tools:read tools:bash）も考慮するには、--jwks-scope-grants を指定します。これにより付与されるツールがさらに制限されます（オペレーターが設定した上限を狭めることはできますが、広げることはできません）。scope クレームと Entra 形式の scp クレームの両方に対応しています。このモードではアクセスはデフォルト拒否です。tools:* スコープを含まないトークンにはツールが一切付与されないため、トークンでは必要なツールを明示的に要求する必要があります。

静的トークンへのフォールバックなし。 oauth モードとは異なり、jwks モードでは外部発行の JWT のみを受け入れます。--auth-token は拒否されます。

注： MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL はこのモードとは無関係です。これは、--auth oauth モードで platter 自身の発行者を http 経由で提供する場合にのみ関係します。外部の https 発行者には、このフラグは不要です。--auth jwks で平文の http 発行者（例：localhost 上の Keycloak）を指定すると、platter は警告を出し、RFC 9728 メタデータの公開をスキップしますが、トークン検証は引き続き機能します。

TLS（HTTPS）

HTTPS で提供するには、PEM 形式の証明書と秘密鍵を指定します。

platter -t http --tls-cert cert.pem --tls-key key.pem

--tls-cert と --tls-key は、必ず両方を指定してください。指定すると、サーバーは平文の HTTP ではなく HTTPS で待ち受けます。

開発環境または信頼された内部用途向けに自己署名証明書を生成するには、次のようにします。

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=myserver'
platter -t http --tls-cert cert.pem --tls-key key.pem

Stdio モード

Claude Desktop、Cursor、その他の MCP クライアントでサブプロセスを起動して使用する場合：

{
  "mcpServers": {
    "platter": {
      "command": "/path/to/platter"
    }
  }
}

HTTP モード（StreamableHTTP）

ブラウザベースのエージェントやリモート接続向け：

platter -t http -p 3100

サーバーは /mcp に単一のエンドポイントを公開し、次の処理を行います。

• POST /mcp - JSON-RPC メッセージ（初期化、ツール呼び出し）
• GET /mcp - SSE 通知ストリーム
• DELETE /mcp - セッションの終了

デフォルトでは、すべてのオリジンに対して CORS が有効です（リクエストの Origin を反映します）。特定のオリジンに制限するには、次のようにします。

platter -t http --cors-origin https://myapp.example.com

セッションは、StreamableHTTP 仕様に従い、Mcp-Session-Id ヘッダーを使って管理されます。

サーバーは、DNS リバインディング攻撃を防ぐために Host ヘッダーを検証します。--cors-origin が設定されている場合、Origin ヘッダーも（CORS レスポンスヘッダーだけでなく）サーバー側で検証されます。

トレイモード（Linux）

システムトレイアイコンを備えた永続的なバックグラウンドサービスとして platter を実行します。

platter --tray

これは --transport=http を指定した場合と同じ動作になり、次の機能が追加されます。

• システムトレイアイコン：DBus（StatusNotifierItem プロトコル）経由で表示され、KDE、GNOME（AppIndicator 拡張機能を使用）、その他のデスクトップ環境に対応しています。
• 永続的な設定：~/.config/platter/config.json に保存される認証トークン、有効なツール、ポート、ホスト、作業ディレクトリは、再起動後も保持されます。
• 動的なツールの切り替え：トレイメニューから個々のツールを実行時に有効または無効にできます。変更は保存され、すぐに反映されます。
• 認証トークンの管理：サーバー URL または認証トークンをクリップボードにコピーしたり、トークンを再生成したりできます。利用可能な場合、トークンはシステムのキーリングに保存され、利用できない場合は設定ファイルに保存されます。
• サーバーの制御：トレイメニューから HTTP サーバーを起動、停止、再起動できます。

Linux インストーラー

linux/install.sh スクリプトは、ユーザーレベルでインストールを実行します（sudo は不要です）。

./linux/install.sh                  # install
./linux/install.sh --uninstall      # remove

次のものがインストールされます。

• ~/.local/bin/platter — バイナリ
• ~/.local/share/applications/platter.desktop — デスクトップランチャーのエントリー
• ~/.local/share/icons/hicolor/scalable/apps/platter.svg — アプリケーションアイコン
• ~/.config/systemd/user/platter.service — 自動起動用の systemd ユーザーユニット

セキュリティ

ネットワーク（HTTP モード）

• TLS（HTTPS） - --tls-cert と --tls-key による任意の通信暗号化です。PEM エンコードされた証明書ファイルとキー ファイルを使用する Node.js の https モジュールを利用します。
• OAuth 2.1 + PKCE（--auth oauth、デフォルト） - MCP クライアントは PKCE を使用する認可コードフローで認証します（RFC 7636）。動的クライアント登録（RFC 7591）とトークン失効（RFC 7009）に対応しています。
• 外部 JWKS / OIDC（--auth jwks） - リソースサーバーモードです。platter は外部発行者（Auth0、Keycloak、Okta、Entra）から発行された JWT アクセストークンを、その発行者の JWKS に照らして検証し、署名、iss、aud、exp を確認します。非対称アルゴリズムのみをサポートします（alg: none と HMAC は拒否されます）。設定については、認証の 外部 JWKS / OIDC セクションを参照してください。
• 帯域外の同意確認 - OAuth 同意ページでは確認コードが必要です。このコードは platter のオペレーターにのみ表示されます（stderr またはデスクトップ通知経由）。これにより、CSRF 攻撃やクロスオリジン攻撃によって認可リクエストが自動承認されるのを防ぎます。同意ページは X-Frame-Options: DENY、Sec-Fetch-Site の検証、Origin ヘッダーの確認によっても保護されます。
• ベアラートークン認証 - 静的なベアラートークン（RFC 6750）は、oauth モードではフォールバックとして、bearer モードでは唯一の認証方式として利用できます。--auth-token を指定するか --auth none を設定しない限り、起動時にランダムな 256 ビットトークンが生成されます。
• Host ヘッダーの検証 - DNS リバインディング攻撃を防ぎます。ローカルホストにバインドする場合は 127.0.0.1、localhost、::1 のみを受け入れます。リモートにバインドする場合は、指定された --host のみを受け入れます。
• Origin の検証 - --cors-origin に特定の Origin を設定した場合、一致しない Origin ヘッダーを含むリクエストは、CORS レスポンスヘッダーでフィルタリングするだけでなく、403 で明示的に拒否されます。

制限事項（ベストエフォート）

--tools、--allow-path、--allow-command は多層防御のための制御です。セキュリティの水準を大幅に高めますが、サンドボックスではありません。脅威モデルでこれらに依存する前に、以下の制限事項を理解しておく必要があります。

得意な点

• ツールの選択は登録時に適用されます。無効化されたツールは MCP プロトコル経由で公開されることはありません。クライアントがそれらを呼び出したり、検出したりする方法はありません。
• パスの検証では、比較の前に対象と各許可パスの両方に対して realpath() を使ってシンボリックリンクを解決し、../ やシンボリックリンクされたディレクトリを介したパス traversal を防ぎます。まだ存在しない書き込み先については、最も近い既存の親ディレクトリを解決します。
• コマンドの検証では、正規表現パターンをコマンド文字列全体に一致するよう固定し、&& malicious-command を追加するような単純な回避を防ぎます。

既知の制限と回避方法

• Bash には本質的に制限がありません。 Bash ツールが有効な場合、十分に工夫されたコマンドで --allow-path を完全に回避できます（例：cat /etc/passwd）。--allow-path を設定し、--allow-command を設定しない場合、または --tools から bash を削除しない場合は、起動時に警告が表示されます。強力なファイルアクセス制御を実現するには、bash を無効にする（--tools read,write,edit,glob,grep）か、--allow-path と厳格な --allow-command 許可リストを併用してください。
• js ツールはセキュリティサンドボックスではありません。 コードは Node.js の vm コンテキスト内で実行されますが、Node.js の公式ドキュメントでは、これがセキュリティ機構ではないと明記されています。信頼できないコードは、既知の手法を使ってコンテキストから脱出できます。脱出しなくても、ランタイムからは fetch（プライベートアドレスやループバックアドレスを含む、任意のネットワークアクセス）、Buffer、および unpkg.com やその他の URL から任意のコードをダウンロードして実行する load() ヘルパーが利用できます。--allow-path、--allow-command、--sandbox、--sandbox-allow-url はいずれも js ツールには適用されません。これらのフラグが影響するのはファイルツールと bash ツールのみです。js ツールが有効な場合、このサーバーは、制限のない bash とほぼ同等の影響範囲を持つものとして扱ってください。無効にするには、--tools read,write,edit,bash,glob,grep を指定します。強力な隔離を実現するには、platter をコンテナーまたは VM 内で実行してください。
• コマンドの正規表現は生の文字列に対して動作します。 シェル構文は解析しません。--allow-command "git( .*)?" のようなパターンでは、rm && git status はブロックされます（文字列全体が一致しないため）が、許可パターンが広すぎる場合など、攻撃者が正規表現には一致しつつ意図しないコードを実行するコマンドを作成する可能性があります。パターンは可能な限り厳密に記述してください。
• シンボリックリンクの TOCTOU。 パスの検証では、チェック時点でシンボリックリンクを解決します。チェックから実際のファイル操作までの間にシンボリックリンクのリンク先が変更されると、検証を回避できます。これはユーザー空間でのパスチェックにおける根本的な制限です。
• Glob／grep の検索範囲。 --allow-path は glob と grep の検索ディレクトリを検証しますが、そのディレクトリツリー内の結果に、範囲外を指すシンボリックリンクが含まれる場合があります。これらのシンボリックリンク先の内容が grep の出力に含まれたり、glob で一覧表示されたりする可能性があります。
• プロセスレベルのサンドボックスはありません。 制限はすべて platter プロセス内のアプリケーションコードによって適用されます。OS レベルの機構（seccomp、namespaces、pledge など）は使用しません。platter 自体、Bun、または依存関係の脆弱性によって、すべての制限が回避される可能性があります。

より強力に隔離するには、just-bash のサンドボックス、Docker コンテナー、またはその両方を使用してください。

サンドボックスモード（just-bash）

サンドボックス化されたコマンド実行のために、仮想ファイルシステムを備えた Bash の TypeScript による再実装である just-bash をオプトインで利用できます。ネイティブプロセスは起動されず、シェルは Bun ランタイム内で完全に実行されます。

platter --sandbox                                               # readwrite fs, no network
platter --sandbox --sandbox-fs memory                           # pure in-memory fs
platter --sandbox --sandbox-fs overlay                          # reads from disk, writes ephemeral
platter --sandbox --sandbox-allow-url "https://api.example.com" # allow network to prefix

ファイルシステムモード

モード	読み取り	書き込み	ユースケース
memory	仮想のみ	仮想のみ	最大限の隔離。ディスクには一切アクセスしません
readwrite（デフォルト）	実ディスク	実ディスク	実ファイルへのアクセスを伴うサンドボックス化された実行
overlay	実ディスク	メモリ内（エフェメラル）	ファイルを変更するリスクなく調査します

ネットワークアクセス

ネットワークアクセスはデフォルトで無効です。--sandbox-allow-url（複数回指定可能）を使用すると、特定のURLプレフィックスへのアクセスを許可できます。プライベートIPおよびループバックIPは常に拒否されます。

platter --sandbox --sandbox-allow-url "https://api.github.com" --sandbox-allow-url "https://registry.npmjs.org"

他の制限との相互作用

• --allow-path：readwrite モードおよび overlay モードでは、許可された各パスがサンドボックスにマウントされます。memory モードでは、--allow-path は無視されます。
• --allow-command：コマンドの正規表現による検証は、サンドボックスがコマンドを実行する前に引き続き適用されます。
• --sandbox は bash と --allow-path に関する警告を抑制します。サンドボックスがファイルシステムの境界を強制するためです。

制限事項

• 完全な bash ではありません。 just-bash は TypeScript による再実装であり、GNU bash とは一部のエッジケースで動作が異なる場合があります。
• ネイティブバイナリは使用できません。 git、node、docker、rg、python などのコマンドは利用できません。bash の組み込み機能と just-bash の組み込みコマンドセットのみ使用できます。
• ベータ版ソフトウェアです。 just-bash は現在も活発に開発されています。本番環境で依存する前に、ワークフローをテストしてください。

コンテナーの分離（Docker）

Docker コンテナー内で platter を実行すると、Linux の名前空間と cgroups による OS レベルの分離が実現します。コンテナーの境界によって、bash ツールがアクセスできる範囲が制限されます。制限のないコマンドであっても、コンテナーに公開されたファイルシステムとネットワークにしかアクセスできません。

# Minimal: no host filesystem, no network
docker run --rm -i --network none ghcr.io/hadriangateway/platter

# Read-only project access, no bash
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work:ro \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --tools read,glob,grep

# Full tools, scoped to a mounted directory
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --allow-path /work

コンテナーによる制御

• ファイルシステムの境界。 明示的にマウントされたパス（-v）のみが表示されます。bash が有効でも、マウントされていないホストパスの読み書きはできません。
• ネットワークの境界。 --network none を指定すると、ネットワークが完全に無効になります。指定しない場合、コンテナーは外部へのアクセスが可能ですが、--network host を使用しない限り、ホスト専用のサービスにはアクセスできません。
• プロセスの分離。 コンテナー内のプロセスからホストのプロセスを参照したり、シグナルを送信したりすることはできません。
• リソース制限。 Docker の --memory、--cpus、--pids-limit フラグを使用してリソース使用量に上限を設け、サービス拒否を防止できます。

コンテナーと VM の比較

コンテナーはホストカーネルを共有し、分離はカーネル機能（名前空間、cgroups、seccomp）によって実施されます。カーネルの脆弱性や、コンテナーの設定ミス（例：--privileged）によって境界が破られる可能性があります。VM は仮想化されたハードウェア上で個別のカーネルを実行するため、ゲスト環境が侵害されても、ホストが直接さらされることはありません。カーネルの脆弱性を悪用する可能性のある信頼できないコードが脅威モデルに含まれる場合は、platter を VM 内（または Kata Containers や Firecracker のような VM ベースのコンテナーランタイム内）で実行してください。AI エージェントによる被害範囲の制限など、ほとんどのユースケースでは、適切に設定されたコンテナー（非 root、ケイパビリティを削除、--network none）で十分です。

サンドボックスとコンテナーの併用

just-bash サンドボックスと Docker コンテナーは、異なる層を保護します。両方を併用すると、多層防御が実現します。

層	防止するもの
just-bash サンドボックス	任意のネイティブプロセスの実行：git、curl、rm などは使用できません。コマンドは OS のシェルではなく、TypeScript インタープリターで実行されます。
Docker コンテナー	ホストのファイルシステムやネットワークへのアクセス：サンドボックスに不具合がある場合や回避された場合でも、コンテナーによって被害範囲はマウントされたパスと許可されたネットワークに制限されます。

# Maximum isolation: sandbox inside a container, overlay fs, no network
docker run --rm -i --network none \
  -v /home/user/project:/work:ro \
  ghcr.io/hadriangateway/platter --sandbox --sandbox-fs overlay

# Sandbox with controlled network access inside a container
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 \
    --sandbox --sandbox-allow-url "https://api.github.com"

最高レベルのセキュリティを確保するには、コンテナーを非 root ユーザー（--user）として実行し、すべてのケイパビリティ（--cap-drop ALL）を削除し、必要な書き込み用に tmpdir を設定したうえでファイルシステムを読み取り専用（--read-only）にしてください。

docker run --rm -p 3100:3100 \
  --user 1000:1000 \
  --cap-drop ALL \
  --read-only --tmpfs /tmp \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --sandbox

パスのマウント、ネットワーク、カスタムイメージのビルドなど、使用方法の詳細はDockerを参照してください。

Docker

Docker イメージは Debian Bookworm (slim) をベースにしており、ripgrep が含まれています。マルチアーキテクチャイメージ（linux/amd64、linux/arm64）は、タグ付きリリースのたびに GitHub Container Registry に公開されます。

docker pull ghcr.io/hadriangateway/platter        # latest release
docker pull ghcr.io/hadriangateway/platter:1.0.0  # specific version

stdio モードでの実行

標準入力／標準出力を介して JSON-RPC メッセージをパイプします。

docker run --rm -i ghcr.io/hadriangateway/platter

HTTP モードでの実行

ホストからポートにアクセスできるよう、コンテナー内で 0.0.0.0 にバインドします。

docker run --rm -p 3100:3100 ghcr.io/hadriangateway/platter -t http --host 0.0.0.0

パスのマウント

ホストのディレクトリをコンテナにマウントし、--cwd または --allow-path を使って platter にアクセス権を付与します。

# Mount a project directory as the working directory
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0

# Mount read-only
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work:ro \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --tools read,glob,grep

# Mount multiple directories with path restrictions
docker run --rm -p 3100:3100 \
  -v /home/user/project:/project \
  -v /tmp/scratch:/scratch \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 \
    --cwd /project \
    --allow-path /project --allow-path /scratch

ネットワーク

デフォルトでは、コンテナは外部ネットワークに完全にアクセスできます。Docker のネットワークオプションを使って制限できます。

# No network access (file-only tools)
docker run --rm --network none -i ghcr.io/hadriangateway/platter

# Access host services (e.g. a local database)
docker run --rm -p 3100:3100 --network host ghcr.io/hadriangateway/platter -t http --host 0.0.0.0

実行時に追加のソフトウェアをインストールする

イメージは Debian を使用しているため、実行時に apt-get でパッケージをインストールできます。手早く試すには便利ですが、起動が遅くなります。本番環境では、代わりにカスタムイメージをビルドしてください（下記を参照）。

docker run --rm -p 3100:3100 ghcr.io/hadriangateway/platter \
  bash -c "apt-get update && apt-get install -y git nodejs && exec platter -t http --host 0.0.0.0"

または、対話形式で操作します。

docker run --rm -it --entrypoint bash ghcr.io/hadriangateway/platter
# inside the container:
apt-get update && apt-get install -y git python3
platter -t http --host 0.0.0.0

カスタムイメージのビルド

platter イメージをベースにツールを追加し、すぐに使える環境を構築します。

FROM ghcr.io/hadriangateway/platter:latest

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      git \
      curl \
      python3 \
      nodejs \
      npm \
 && rm -rf /var/lib/apt/lists/*

ビルドして実行します。

docker build -t my-platter .
docker run --rm -p 3100:3100 -v ~/project:/work my-platter -t http --host 0.0.0.0

イメージをローカルでビルドする

docker build -t platter .
docker run --rm -i platter

ビルド

bun install
bun run build        # bundle to dist/
bun run compile      # standalone binary for current platform -> ./platter
bun run compile:all  # cross-compile for linux-x64, linux-arm64, darwin-x64, darwin-arm64
bun run format       # format with Biome
bun run format:check # check formatting
bun run lint         # lint with Biome
bun run lint:fix     # lint and auto-fix with Biome
bun run typecheck    # typecheck with TypeScript
bun run test         # run tests

ライセンス

MIT