> ## 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 サーバーを BRICKS ワークスペースとペアリングし、JWT 認証を有効化します

デフォルトでは Buttress サーバーは**パブリックモード**で動作します。LAN 上の任意のクライアントが認証なしで接続できます。**バインド**するとサーバーが 1 つの BRICKS ワークスペースに紐付き、すべての WebSocket とファイル転送リクエストに有効なワークスペーススコープ JWT が必要なモードに切り替わります。

| 状態     | 検出アナウンス                                    | WebSocket 認証             | HTTP ファイル転送              |
| ------ | ------------------------------------------ | ------------------------ | ------------------------ |
| 未バインド  | `authentication.required = false`          | オープン                     | オープン                     |
| バインド済み | `authentication.required = true`（`kid` 付き） | JWT を検証、ワークスペースが一致する必要あり | JWT を検証、ワークスペースが一致する必要あり |

バインドは一方向のペアリングです。1 つの Buttress サーバーは同時に 1 つのワークスペースにしか属せません。バインド済みサーバーは未認証接続を WebSocket クローズコード `1008` で拒否します。

## 前提条件

* Buttress サーバーがローカルにインストール済み（[インストール](/ja/buttress/installation)を参照）
* [BRICKS CLI](/ja/cli) がインストール済み
* ワークスペースにサインイン済み：`bricks auth login <passcode>`

## サーバーをバインド

Buttress サーバーが動いているのと同じマシンでバインドコマンドを実行します。CLI はローカルのサーバー ID を自動検出し、サーバーが起動時に読み込む小さな `state.json` を書き込みます。

```bash theme={null}
bricks buttress bind
```

自動検出された ID を上書きしたり、サーバーに表示名を付けたり、デフォルト以外の場所に state ファイルを書き込むには：

```bash theme={null}
bricks buttress bind \
  --server-id buttress-mac-studio \
  --name "Studio LLM" \
  --state-dir /etc/buttress
```

ヘッドレスやリモートのセットアップでは、state JSON を stdout に出力して自分で書き込むこともできます：

```bash theme={null}
bricks buttress bind --print > /etc/buttress/state.json
```

<Warning>
  バインド後は Buttress サーバーを再起動してください。state ファイルは起動時に一度だけ読まれるため、再起動しないとサーバーはパブリックモードのまま動作し続けます。
</Warning>

### 書き込まれる内容

state ファイルはデフォルトで `~/.bricks-cli/buttress/state.json` に置かれます。`--state-dir <path>` でディレクトリを上書きできます。

```json theme={null}
{
  "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 自動検出](/ja/buttress/autodiscovery#署名付きアナウンス)を参照してください。

<Warning>
  `state.json` は秘密情報として扱ってください。`serverKeyPair.privateKeyPkcs8` フィールドを読めば、誰でもこのサーバーとして UDP アナウンスに署名できます。`bricks buttress bind --print` で JSON を stdout に出力する場合も同じ理由で stderr に警告が出ます。
</Warning>

`bricks buttress bind` を再実行すると新しいアナウンス鍵ペアが生成され、登録済みの公開鍵が更新されます。古い鍵をキャッシュしている launcher は、クラウドから新しい鍵を取得するまでこのサーバーを信頼しなくなります。

## バインドを確認

`bricks buttress status` はローカル state ファイルとワークスペース側のバインド済みサーバー一覧を出力します。

```bash theme={null}
bricks buttress status
```

機械可読形式が必要な場合は `--json` を付けます：

```bash theme={null}
bricks buttress status --json
```

JSON の形は `{ "local": <state.json または null>, "remote": <[{ serverId, name, boundAt, lastSeenAt }, …]> }` です。

## バインド解除

バインド解除はワークスペースのサーバー記録をクリア**し**、ローカルの state ファイルも削除します。

```bash theme={null}
bricks buttress unbind
```

サーバー側のみ取り消してローカル state を残したい場合：

```bash theme={null}
bricks buttress unbind --keep-local
```

バインドを解除したらサーバーをパブリックモードに戻すために再起動してください。

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

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

```bash theme={null}
# デフォルト 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>` クエリ文字列で送信してください。

<Tip>
  発行されたトークンは CLI のセッショントークンに紐付いています。CLI のワークスペーストークンを取り消すと、そのセッションから発行された Buttress access token はすべて無効になります。
</Tip>

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

| 症状                                                       | 原因と思われるもの                             | 対処                                     |
| -------------------------------------------------------- | ------------------------------------- | -------------------------------------- |
| `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」と表示       | サーバーがデバイスとは別のワークスペースにバインドされている        | デバイスのワークスペースに合わせて再バインド、またはデバイスを移動      |

## 次のステップ

<CardGroup cols={2}>
  <Card title="LAN 自動検出" icon="broadcast-tower" href="/ja/buttress/autodiscovery">
    Foundation デバイスが LAN 上でバインド済みサーバーを見つける仕組み。
  </Card>

  <Card title="Foundation から利用" icon="mobile" href="/ja/foundation/buttress">
    各 LLM/STT brick でオフロードを設定。
  </Card>
</CardGroup>