跳轉到主要內容

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 工作區配對，並切換至「所有 WebSocket 與檔案傳輸請求皆須攜帶有效工作區 JWT」的模式。
狀態探索通告WebSocket 認證HTTP 檔案傳輸
未繫結authentication.required = false開放開放
已繫結authentication.required = true（含 kid）驗證 JWT，工作區須相符驗證 JWT，工作區須相符
繫結為單向配對：一台 Buttress 伺服器一次只能屬於一個工作區。已繫結的伺服器會以 WebSocket close code 1008 拒絕未認證的連線。

​
前置需求

  • 已於本機安裝 Buttress 伺服器（請參閱安裝）
  • 已安裝 BRICKS CLI
  • 已登入工作區：bricks auth login <passcode>

​
繫結伺服器

於執行 Buttress 伺服器的同一台機器執行繫結指令。CLI 會自動偵測本機的 server 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": "<工作區 id>",
    "name": "<工作區名稱>",
    "serverId": "<伺服器 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 探索封包），私鑰則保留在本機；簽署過的通告詳見區域網路自動探索。
請將 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
解除繫結後請重新啟動 Buttress 伺服器以回到公開模式。

​
核發長期 access token

Foundation launcher 會自動透過 BRICKS 雲端取得短期 token。對於非互動式呼叫端 — CI 指令碼、CTOR 代理、ACP bridge — 可一次核發長期 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>。
核發的 token 與您的 CLI session token 綁定。撤銷 CLI 工作區 token 將使該 session 核發的所有 Buttress access token 一併失效。

​
疑難排解

症狀可能原因解決方式
Could not detect a local server id.machine ID 偵測失敗（沙箱或缺少識別資訊的容器）明確傳入 --server-id <id>
Not logged in. Use bricks auth login first.沒有有效的 CLI profile執行 bricks auth login <passcode>
bind 後伺服器仍接受未認證連線伺服器未重新啟動重新啟動 bricks-buttress
unbind 顯示 <serverId> was not bound to this workspace.伺服器原本就未繫結，或繫結至其他工作區執行 bricks buttress status 確認實際繫結狀態
Foundation 裝置出現「no LAN provider is registered」伺服器繫結的工作區與裝置不同將伺服器重新繫結至裝置所在工作區，或調整裝置歸屬

​
下一步

區域網路自動探索

Foundation 裝置如何於區域網路找到已繫結的伺服器。

從 Foundation 使用

於各 LLM/STT brick 設定卸載行為。