メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt

Use this file to discover all available pages before exploring further.

デフォルトでは Buttress サーバーはパブリックモードで動作します。LAN 上の任意のクライアントが認証なしで接続できます。バインドするとサーバーが 1 つの BRICKS ワークスペースに紐付き、すべての WebSocket とファイル転送リクエストに有効なワークスペーススコープ JWT が必要なモードに切り替わります。
状態検出アナウンスWebSocket 認証HTTP ファイル転送
未バインドauthentication.required = falseオープンオープン
バインド済みauthentication.required = true（kid 付き）JWT を検証、ワークスペースが一致する必要ありJWT を検証、ワークスペースが一致する必要あり
バインドは一方向のペアリングです。1 つの Buttress サーバーは同時に 1 つのワークスペースにしか属せません。バインド済みサーバーは未認証接続を WebSocket クローズコード 1008 で拒否します。

​
前提条件

  • Buttress サーバーがローカルにインストール済み（インストールを参照）
  • BRICKS CLI がインストール済み
  • ワークスペースにサインイン済み：bricks auth login <passcode>

​
サーバーをバインド

Buttress サーバーが動いているのと同じマシンでバインドコマンドを実行します。CLI はローカルのサーバー ID を自動検出し、サーバーが起動時に読み込む小さな state.json を書き込みます。 
bricks buttress bind
自動検出された ID を上書きしたり、サーバーに表示名を付けたり、デフォルト以外の場所に state ファイルを書き込むには： 
bricks buttress bind \
  --server-id buttress-mac-studio \
  --name "Studio LLM" \
  --state-dir /etc/buttress
ヘッドレスやリモートのセットアップでは、state JSON を stdout に出力して自分で書き込むこともできます： 
bricks buttress bind --print > /etc/buttress/state.json
バインド後は Buttress サーバーを再起動してください。state ファイルは起動時に一度だけ読まれるため、再起動しないとサーバーはパブリックモードのまま動作し続けます。

​
書き込まれる内容

state ファイルはデフォルトで ~/.bricks-cli/buttress/state.json に置かれます。--state-dir <path> でディレクトリを上書きできます。 
{
  "workspace": {
    "id": "<workspace id>",
    "name": "<workspace name>",
    "serverId": "<server id>",
    "issuerPublicKey": "-----BEGIN PUBLIC KEY-----\n…",
    "kid": "<key id>",
    "boundAt": "2026-05-08T12:00:00.000Z"
  },
  "serverKeyPair": {
    "publicKeySpki": "<base64 SPKI>",
    "privateKeyPkcs8": "<base64 PKCS8>",
    "kid": "<announce kid>"
  }
}
  • workspace.issuerPublicKey はワークスペースの Ed25519 公開鍵で、サーバーが受け取った各 access token の検証に使用します。
  • serverKeyPair は bind のたびにローカルで生成されるサーバー専用の Ed25519 アナウンス鍵ペアです。公開鍵はクラウドに登録され（launcher が署名付き UDP 検出パケットを検証できるように）、秘密鍵はディスク上に残ります。署名付きアナウンスの詳細は LAN 自動検出を参照してください。
state.json は秘密情報として扱ってください。serverKeyPair.privateKeyPkcs8 フィールドを読めば、誰でもこのサーバーとして UDP アナウンスに署名できます。bricks buttress bind --print で JSON を stdout に出力する場合も同じ理由で stderr に警告が出ます。
bricks buttress bind を再実行すると新しいアナウンス鍵ペアが生成され、登録済みの公開鍵が更新されます。古い鍵をキャッシュしている launcher は、クラウドから新しい鍵を取得するまでこのサーバーを信頼しなくなります。

​
バインドを確認

bricks buttress status はローカル state ファイルとワークスペース側のバインド済みサーバー一覧を出力します。 
bricks buttress status
機械可読形式が必要な場合は --json を付けます： 
bricks buttress status --json
JSON の形は { "local": <state.json または null>, "remote": <[{ serverId, name, boundAt, lastSeenAt }, …]> } です。

​
バインド解除

バインド解除はワークスペースのサーバー記録をクリアし、ローカルの state ファイルも削除します。 
bricks buttress unbind
サーバー側のみ取り消してローカル state を残したい場合： 
bricks buttress unbind --keep-local
バインドを解除したらサーバーをパブリックモードに戻すために再起動してください。

​
長期間有効な access token を発行

Foundation launcher は短命なトークンを BRICKS クラウド経由で自動取得します。ヘッドレスな呼び出し元（CI スクリプト、CTOR エージェント、ACP ブリッジ）には、長期間有効な access token を一度発行して使い回します。 
# デフォルト 30 日 TTL
bricks buttress issue-token

# カスタム TTL（秒）、スクリプト用 JSON 出力
bricks buttress issue-token --ttl 3600 --json
CLI は JWT と有効期限を表示します。Authorization: Bearer <token> ヘッダー、または WebSocket URL の ?access_token=<token> クエリ文字列で送信してください。
発行されたトークンは CLI のセッショントークンに紐付いています。CLI のワークスペーストークンを取り消すと、そのセッションから発行された Buttress access token はすべて無効になります。

​
トラブルシューティング

症状原因と思われるもの対処
Could not detect a local server id.machine ID 検出に失敗（識別情報のないサンドボックス／コンテナ）--server-id <id> を明示的に指定
Not logged in. Use bricks auth login first.有効な CLI プロファイルがないbricks auth login <passcode> を実行
bind 後もサーバーが未認証接続を受け付けるサーバーを再起動していないbricks-buttress を再起動
unbind で <serverId> was not bound to this workspace.サーバーが元々未バインド、または別のワークスペースにバインド済みbricks buttress status で実際のバインド状況を確認
Foundation デバイスに「no LAN provider is registered」と表示サーバーがデバイスとは別のワークスペースにバインドされているデバイスのワークスペースに合わせて再バインド、またはデバイスを移動

​
次のステップ

LAN 自動検出

Foundation デバイスが LAN 上でバインド済みサーバーを見つける仕組み。

Foundation から利用

各 LLM/STT brick でオフロードを設定。