Installation

The Buttress server ships as a standalone executable, bricks-buttress, for macOS, Linux, and Windows. No Node.js runtime is required. If you prefer, you can also install it from npm or Bun. For GPU acceleration on Linux, install CUDA or Vulkan drivers before running the installer — it picks the matching build based on what it finds.

Hardware

Resource	Recommended
GPU	NVIDIA (CUDA), AMD/Intel (Vulkan), or Apple Silicon (Metal)
RAM	At least 2× the size of the largest model you plan to load
Disk	Enough free space in `cache_dir` to hold every model you download
Network	Wired LAN — UDP broadcasts must reach Foundation devices

The server runs without a GPU but the throughput drops sharply, and capability scoring will mark the host as a less-preferred backend.

Install

macOS
Linux
Windows
npm / Bun

curl -fsSL https://cdn.bricks.tools/bricks-buttress/release/install.sh | sh

The script detects your architecture (Apple Silicon or Intel) and installs bricks-buttress to ~/.bricks-cli/bin. Metal acceleration is part of the default build, so there is nothing extra to select.If ~/.bricks-cli/bin is not on your PATH, the script appends it to your shell profile (~/.zshrc, ~/.bash_profile, or ~/.config/fish/config.fish) and tells you to restart your shell.

curl -fsSL https://cdn.bricks.tools/bricks-buttress/release/install.sh | sh

The script detects your architecture (x86_64 or ARM64) and your GPU accelerator, then installs bricks-buttress to ~/.bricks-cli/bin.If ~/.bricks-cli/bin is not on your PATH, the script appends it to your shell profile (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, or ~/.profile) and tells you to restart your shell.

musl-based distributions (Alpine and similar) are not supported. The GGML native modules ship glibc builds only, and the installer stops with an error rather than installing something that cannot load.

Run in PowerShell:

irm https://cdn.bricks.tools/bricks-buttress/release/install.ps1 | iex

The script detects your architecture (x64 or ARM64) and GPU accelerator, then installs bricks-buttress.exe to %LOCALAPPDATA%\Programs\bricks-cli\bin\.If the install directory is not on your user PATH, the script prints the command to add it. You can also add it from Settings > System > About > Advanced system settings > Environment Variables.Extraction uses tar.exe, which ships with Windows 10 1803 and later.

The server is also published on npm. This method requires Node.js 22+ or Bun.

# npm
npm install -g @fugood/buttress-server

# Bun
bun add -g @fugood/buttress-server

On a fresh Apple Silicon Mac, install with Bun for faster cold starts and lower memory overhead.

The standalone installers share their install directory with BRICKS CLI, so a single PATH entry covers both tools. Confirm the install:

bricks-buttress --version

Native modules

The standalone binary cannot embed the GGML, ONNX Runtime, sharp, and oxc-transform native addons. The installer downloads them from the npm registry into a node_modules directory next to the executable, pinned to the versions the binary was built against. It also places the status dashboard (public/status.html) there, plus the MLX bridge script on macOS. Each install rebuilds that directory from scratch, so upgrading never leaves a stale native module behind. Set BUTTRESS_NPM_REGISTRY to download the native packages from a mirror instead of https://registry.npmjs.org.

GPU acceleration variants

The GGML backends ship one build per accelerator. The installer probes the host, picks the best supported one, and downloads only that variant alongside the default CPU build.

Platform	Detection order	Signals
Linux	CUDA → Vulkan → Snapdragon → default	`nvidia-smi` or `libcuda.so`; `libvulkan.so.1`; a Qualcomm ARM64 SoC
Windows	CUDA → Vulkan → default	`nvidia-smi` or an NVIDIA display adapter; `vulkan-1.dll`
macOS	default	Metal is part of the default build

Override the choice when detection guesses wrong — for example on a machine whose drivers are installed after the fact:

curl -fsSL https://cdn.bricks.tools/bricks-buttress/release/install.sh | sh -s -- --ggml-variant=cuda

irm https://cdn.bricks.tools/bricks-buttress/release/install.ps1 -OutFile install.ps1
.\install.ps1 -GgmlVariant cuda

Accepted values are auto (the default), default, cuda, vulkan, snapdragon (Linux only), and all. Use all to download every variant — larger, but portable across hosts if you image the install directory.

Running install.sh from an MSYS or Git Bash shell on Windows skips GPU probing, because the results are unreliable there. Pass --ggml-variant explicitly, or use the PowerShell installer.

Installer options

macOS / Linux	Windows	Description
`--beta`	`-Beta`	Install from the beta channel
`--dir=<path>`	`-InstallDir <path>`	Install somewhere other than the shared BRICKS CLI directory
`--ggml-variant=<variant>`	`-GgmlVariant <variant>`	Override accelerator detection
`--help`	—	Print usage and exit

Run the server

Without a config, the server starts on port 2080 with sensible defaults:

bricks-buttress

With a TOML config:

bricks-buttress --config ./config.toml

Pass an inline TOML string instead of a path with the same flag:

bricks-buttress --config '[server]
port = 3000

[[generators]]
type = "ggml-llm"
[generators.model]
repo_id = "ggml-org/gemma-3-270m-qat-GGUF"'

See the configuration reference for the full schema.

CLI flags

Flag	Description
`-p, --port <port>`	Port to listen on (default: `2080`)
`-c, --config <path\|toml>`	Path to a TOML file or an inline TOML string
`-v, --version`	Print the server version
`-h, --help`	Show help

The port resolves in this order: --port flag → [server] port in TOML → default 2080. bricks-buttress also takes one subcommand, update — see Update below.

Environment variables

Variable	Effect
`NODE_ENV`	Set to `development` for verbose logs
`ENABLE_OPENAI_COMPAT_ENDPOINT`	Set to `1` to enable the OpenAI-compat endpoint
`ENABLE_ANTHROPIC_MESSAGES_ENDPOINT`	Set to `1` to enable the Anthropic messages endpoint
`HF_TOKEN`	Hugging Face token for downloading gated models

System environment variables override values set under [env] in your TOML config.

macOS GPU memory

On Apple Silicon Macs, the GPU is allowed about 70% of system memory by default. To raise the cap before loading large models:

# Allow up to 128 GB on a 128 GB host
sudo sysctl iogpu.wired_limit_mb=137438

# Restore the default
sudo sysctl iogpu.wired_limit_mb=0

Verify

When the server starts, it prints a LAN-reachable URL like Visit http://<ip>:2080/status to see status via LAN. Open that URL — or http://localhost:2080/status from the same machine — to load the status dashboard. The dashboard shows, per backend (GGML-LLM, GGML-STT, MLX-LLM):

The list of loaded generators and which ones currently hold an active model context
Parallel slot usage and queued requests for STT
Recent model-load history and completion / transcription history (collapsible)

A Refresh button on the page polls the same data on demand. There is no auth on /status — host the server on a trusted LAN. For machine-readable output, query the JSON endpoints directly:

# Server identity, capabilities, generators, auth status
curl http://localhost:2080/buttress/info

# Live generator/queue/history snapshot (same data as the dashboard)
curl http://localhost:2080/buttress/status

/buttress/info is what Foundation devices read during HTTP fallback discovery — see LAN auto-discovery.

Beta channel

curl -fsSL https://cdn.bricks.tools/bricks-buttress/beta/install.sh | sh -s -- --beta

irm https://cdn.bricks.tools/bricks-buttress/beta/install.ps1 -OutFile install-beta.ps1
.\install-beta.ps1 -Beta

The executable is named bricks-buttress on both channels, so installing the beta replaces an existing stable install. The two channels cannot coexist in the same directory — pass --dir / -InstallDir if you need both.

Update

Run bricks-buttress update to update an existing install in place. It detects how the server was installed — standalone binary, npm global, or Bun global — and runs the matching update:

Standalone binary — re-runs the CDN installer, which replaces the executable and rebuilds the native modules directory, picking up any native package version changes in the new release. The existing install directory is reused, so an override passed to --dir is preserved.
npm / Bun — reinstalls the global @fugood/buttress-server package.

bricks-buttress update         # prompts before updating
bricks-buttress update -y      # non-interactive
bricks-buttress update --check # report only, don't install

The release channel is inferred from the running version’s pre-release suffix. Version availability comes from the npm dist-tags for npm and Bun installs, and from the CDN release metadata for binary installs. When a newer version is available, the running server also prints an upgrade notice with this command.

Option	Description
`-y, --yes`	Skip confirmation prompts
`--check`	Only report whether a newer version exists — exit code `0` up to date, `1` update available, `2` could not determine
`--channel <release\|beta>`	Override the detected channel
`--ggml-variant <variant>`	Pass an accelerator variant through to the installer
`-h, --help`	Show help for the subcommand

If the detected method fails, the command offers the binary installer as a fallback. That path also works when the native modules are missing or broken — update runs before the server’s backends are loaded, so a damaged install can repair itself. On Windows the installer moves a locked native modules directory aside instead of failing, so the server can update itself while running.

Uninstall

macOS / Linux
Windows
npm / Bun

curl -fsSL https://cdn.bricks.tools/bricks-buttress/release/uninstall.sh | sh

irm https://cdn.bricks.tools/bricks-buttress/release/uninstall.ps1 | iex

# npm
npm uninstall -g @fugood/buttress-server

# Bun
bun remove -g @fugood/buttress-server

The uninstaller removes only Buttress-owned files — the executable, the native modules directory, the status page, and the MLX bridge script. Because the directory is shared with BRICKS CLI, it is never deleted. Pass --dir / -InstallDir if you installed somewhere else.

Overview

Guides

Changelog

Hardware

Install

Native modules

GPU acceleration variants

Installer options

Run the server

CLI flags

Environment variables

macOS GPU memory

Verify

Beta channel

Update

Uninstall

Next steps

Configuration

Workspace binding

​Hardware

​Install

​Native modules

​GPU acceleration variants

​Installer options

​Run the server

​CLI flags

​Environment variables

​macOS GPU memory

​Verify

​Beta channel

​Update

​Uninstall

​Next steps

Configuration

Workspace binding

Hardware

Install

Native modules

GPU acceleration variants

Installer options

Run the server

CLI flags

Environment variables

macOS GPU memory

Verify

Beta channel

Update

Uninstall

Next steps