Skip to main content
BRICKS Buttress splits cleanly into four layers — clients, servers, backend cores, and shared hardware guardrails — connected by a JSON-RPC WebSocket protocol and a UDP autodiscovery transport. The diagram below is the target architecture; the Implemented vs planned section calls out what ships today and what’s still on the roadmap.

​
Complete architecture

Solid orange arrows are runtime data paths. Dashed green arrows mark where the Hardware Guardrails package is reused on both sides — the same code runs on the client and server. Dashed gray nodes (Thermal Printer, Future Backends) are on the roadmap but not yet shipped.

​
Layer responsibilities

​
How capability comparison works

When a Foundation device starts a generator, the client and server exchange hardware information so the system can pick the right side to run on:
  1. Client collects local capabilities. GPU/CPU info, available memory, model metadata (layers, embedding size, KV cache requirements).
  2. Client sends capabilities to the server along with the model identifier and requested context size.
  3. Server evaluates both sides by running the same guardrails code on the client’s reported caps and on its own. Each side gets a 0-100 performance score and a memory-fit verdict.
  4. Server returns a recommendation — local, buttress, or either.
  5. Client decides based on its strategy (prefer-local, prefer-buttress, prefer-best) and the recommendation. See Use Buttress from Foundation.
Because client and server share the guardrails package, the scores are directly comparable — there is no calibration drift between sides.

​
Implemented vs planned

​
Implemented

  • Workspace JWT authentication — Ed25519 issuer per workspace, short-lived { k:'ba', w_id, … } access tokens. See Workspace binding.
  • UDP autodiscovery with signed announcements — ANNOUNCE/QUERY/RESPONSE on UDP 8089, with per-backend hardware caps in the announcement. Each bound server signs every packet with its registered Ed25519 announce key; launchers verify the signature with a 30-second replay window. Protocol version is 2.0. See LAN auto-discovery.
  • Generator registry with reference counting — multiple clients can share a loaded model, and the server cleans up automatically when refcount hits zero.
  • Queue management — hardware-aware request queuing for STT, with parallel-slot tracking visible on the /status dashboard.
  • GGML LLM, MLX LLM, GGML STT, GGML TTS, ONNX STT, and ONNX TTS backends — GGML TTS pairs a GGUF backbone with its codec / vocoder GGUF and detects the model family natively. The ONNX backends run on ONNX Runtime (Whisper for STT; Kokoro, VITS, Bert-VITS2, and SpeechT5 for TTS).
  • Capability detection and scoring — same guardrails code on both sides.
  • File transfer for STT — devices upload audio to POST /buttress/upload.
  • Local functions (experimental) — operator-authored .ts / .js files exposed as MCP tools and HTTP endpoints, so agents can run work on the server host. Imports are limited to Node builtins, sibling files, and an allowlist of sqlite3 and sqlite-vec. Unlike every other surface, functions are fail-closed on an unbound server. See Local functions.

​
Planned

  • Docker distribution — pre-built images with CUDA / Vulkan support.
  • Multi-server pool selection — caps-aware ranking when multiple bound servers are present in the same workspace (currently last-seen wins).
  • Thermal printer backend — additional offload target beyond LLM/STT.

Workspace binding

How JWT auth fits into the architecture.

LAN auto-discovery

The UDP transport, announcement payload, and capability scoring.