--config で渡された 1 つの TOML ファイルを読み込みます。各セクションは任意で、省略するとデフォルトが使われます。
最小サンプル
トップレベルセクション
[server]
[runtime]
すべての generator が共有するデフォルト値。[generators.model] の generator 単位の値が優先され、それ以外はここで定義した値が適用されます。
[runtime.session_cache]
ggml-llm generator では、リクエスト間で KV cache の状態をディスクに保持し、同じ prompt 接頭辞を持つ後続の completion で prompt 処理をスキップできます。
キャッシュファイルは
{cache_dir}/.session-state-cache/ に保存されます。
mlx-llm は {cache_dir}/mlx-session-cache/ に別の session cache を持ち、generator ごとに個別設定されます。
[[generators]]
各 [[generators]] ブロックは、サーバーがホストする 1 つのモデルを宣言します。複数モデルを提供する場合はブロックを繰り返します。各ブロックには type、任意の [generators.backend] テーブル、[generators.model] テーブルが含まれます。type は ggml-llm、ggml-stt、ggml-tts、ggml-decision、mlx-llm、onnx-stt、onnx-tts のいずれかです。
共通 [generators.model] キー
すべての generator タイプ（ggml-llm、ggml-stt、ggml-tts、ggml-decision、mlx-llm、onnx-stt、onnx-tts）で共有：
ggml-llm、ggml-stt、ggml-tts、ggml-decision のみで尊重されます。
mlx-llm は量子化をリポジトリ自体から取得し、ONNX バックエンド（onnx-stt、onnx-tts）は代わりに dtype で重みを選択するため、いずれも以下のキーを無視します：
ggml-llm（llama.cpp / GGUF）
[generators.backend] はバックエンド選択とリソース計画のみを制御します。runtime オーバーライド（n_ctx、n_gpu_layers、flash_attn_type など）は [generators.model] の下に置きます。
[generators.backend]
[generators.model] — 上記の共通 ggml キーに加え、すべての [runtime] キーを generator 単位で上書き可能: n_ctx、n_gpu_layers、n_batch、n_ubatch、n_threads、n_parallel、n_cpu_moe、flash_attn_type、cache_type_k、cache_type_v、kv_unified、swa_full、ctx_shift、use_mmap、use_mlock、no_extra_bufts、cpu_mask、cpu_strict、devices。
埋め込みモデル
専用の埋め込みモデルには
embedding = true が必要です。ローカル関数の context.buttress.embedding は、このキーを設定していない generator への呼び出しを拒否します。chat モデルの設定を流用せず、埋め込みモデルには専用の [[generators]] ブロックを用意してください。埋め込み context はネイティブシーケンスを 1 つだけ使うため、並列デコードのスロットは適用されません。語彙のみの context には計算バックエンドがまったくないため、tokenizer の呼び出しにしか応えられません。
同じリポジトリを chat・埋め込み・語彙のみと、異なるモードで複数回ホストできます。モードごとに generator レジストリの別エントリになるので、ある利用側の context が別の利用側の設定を引き継ぐことはありません。Vector Store brick は、このファイルに書かなくてもこれら 2 つのキーをリモートから指定します。
マルチモーダル（mtmd） — 同じリポジトリから対応する mmproj-*.gguf を自動ダウンロード：
Speculative decoding
ggml-stt（whisper.cpp）
[generators.backend]
snapdragon バリアントは Hexagon NPU 上で Whisper を実行します。動作する Qualcomm HTP/FastRPC ランタイムを備えた Linux arm64 ホストで利用でき、OpenCL は含まれません。--ggml-variant=snapdragon でインストールしてください。デフォルトの CPU ビルドはフォールバックとして併せて保持されます。このバリアントは独自の HTP ライブラリを同梱しており、ローダーは ADSP_LIBRARY_PATH をその場所に向け、GGML_HEXAGON_NDEV を 16 に設定します（いずれかを自分で設定している場合は上書きしません）。Hexagon では use_flash_attn が "off" でも常に flash attention が有効になります。
音声認識の Hexagon アクセラレーションは実験的機能です。
[generators.model] — 上記の共通 ggml キーに加え：
Runtime 追加設定 —
ggml-stt のみ、[runtime] の下：
ggml-tts（llama.cpp + codec.cpp）
このバックエンドには phonemizer が組み込まれていないため、NeuTTS は音素ではなく生のテキストを受け取ります。これはデバイス側の generator と同じ制限です。
[generators.backend]
[generators.model] — 上記の共通 ggml キーに加え：
バックボーンと codec を同梱するリポジトリは、ファイル名（
codec、vocoder、wavtokenizer、dac、mimi）で振り分けられます。無関係な codec を複数ホストするリポジトリは量子化の優先度だけでは判別できないため、vocoder_filename を明示的に設定してください。
Runtime 追加設定 — ggml-tts は [generators.runtime] の下：
出力キャッシュ — 合成された WAV はディスク上の
{cache_dir}/.tts-cache/ に、テキスト + モデル + オプションをキーとしてキャッシュされ、同じフレーズは即座に返されます。[generators.runtime.output_cache] で設定します：
ggml-decision（llama.cpp 型付き判定）
choice、score、noul（はい／いいえ）の質問に、キャリブレーションされた確率で答えます。各回答は 1 回のフォワードパスで求められ、token は生成されません。デバイスは Typed Decision (GGML) Generator から、ローカル関数は context.buttress.decide から利用します。
モデルは context の読み込み時にチェックされます。通常の chat モデルや、このビルドが対応していない判定タイプの判定モデルは、理由付きで読み込みに失敗します。同じ generator へのリクエストは 1 件ずつ実行されます。
[generators.backend] — ggml-tts と同じキー：variant、variant_preference、gpu_memory_fraction、cpu_memory_fraction。
[generators.model] — 上記の共通 ggml キーに加え：
mmproj_* キーのいずれかを設定するとプロジェクターが読み込まれ、リクエストでファイルパスまたは data URL の画像を渡せるようになります。モデルのプロンプトに画像の入る場所がない場合、サーバーはプロジェクターを無視して警告をログに出します。
Runtime 追加設定 — ggml-decision は [generators.runtime] の下：
mlx-llm（Apple Silicon）
mlx-llm には [generators.backend] セクションはありません。
初回利用時、バックエンドは {cache_dir}/mlx-env に Python virtualenv を作成し、mlx_lm_package、mlx_vlm_package と、一部の VLM プロセッサが必要とする torch および torchvision をインストールします。既存の venv に mlx_vlm と torch がインポート可能な状態であれば、インストールはスキップされます。
[generators.model] — 共通の repo_id / revision / download に加え：
quantization、filename、preferred_quantizations は使われません。量子化は MLX リポジトリ自体が決定します。
Runtime 追加設定 — mlx-llm 用、[runtime] の下：
onnx-stt（ONNX Runtime / Whisper）
onnx/ サブフォルダから {cache_dir}/{owner}/{repo}/ にダウンロードされ、バックエンドは最終テキストを返す前に部分的な文字起こし結果をストリームします。
[generators.backend]
設定したプロバイダーがどれも初期化できない場合、generator は起動しません。
[generators.model]
Runtime 追加設定 —
[generators.runtime] の下：
グローバルな
[runtime] キー cache_dir、huggingface_token、http_headers も適用されます。
onnx-tts（ONNX Runtime / Kokoro、VITS、SpeechT5）
onnx/ サブフォルダから {cache_dir}/{owner}/{repo}/ にダウンロードされます。
[generators.backend] — 上記の onnx-stt と同じキー：provider、provider_preference、gpu_memory_fraction、cpu_memory_fraction。
[generators.model]
出力キャッシュ — 合成された音声はディスク上の
{cache_dir}/.tts-cache/ に、テキスト + モデル + オプションをキーとしてキャッシュされ、同じフレーズは即座に返されます。[generators.runtime.output_cache] で設定します：
[generators.runtime] の prefer_providers キーと、グローバルな [runtime] キー（cache_dir、huggingface_token、http_headers）は onnx-stt と同様に適用されます。
[autodiscover]
サーバーは UDP 8089 で自身を通知し、同じ LAN の Foundation デバイスから検出可能にします。自動検出はデフォルトで有効です。
autodiscover = false に設定すると検出が完全に無効になります。プロトコルの詳細は自動検出リファレンスを参照してください。
[env]
起動時に適用する環境変数。ただしシステム環境にまだ設定されていない場合のみ反映されます。システム変数とコマンドラインの export が優先されます。
HUGGINGFACE_TOKEN です（HF_TOKEN ではありません）。変数名に依存せず単一の token をすべてのバックエンドに適用したい場合は、代わりに [runtime] huggingface_token を設定してください。
互換エンドポイント
これらのエンドポイントは実験的機能です。スキーマ、エラー形式、CORS デフォルトは変更される可能性があります。
各エンドポイントは環境変数経由でも有効化できます：
ENABLE_OPENAI_COMPAT_ENDPOINT=1 または ENABLE_ANTHROPIC_MESSAGES_ENDPOINT=1。
[functions]
ローカル関数は実験的機能です。エンドポイント、関数ファイルの契約、これらの設定キーはリリース間で変更される可能性があります。
.ts / .js ファイルを MCP ツールと HTTP エンドポイントとして公開します。デフォルトは無効です。
環境変数の同等物：
ENABLE_FUNCTIONS_ENDPOINT=1、BUTTRESS_FUNCTIONS_DIR=<dir>、BUTTRESS_FUNCTIONS_HOT_RELOAD=1、BUTTRESS_FUNCTIONS_ALLOW_UNAUTHENTICATED=1。
ファイルの契約、注入される context、エンドポイント、セキュリティモデルについてはローカル関数を参照してください。
[[agents]]
Agents は実験的機能です。これらの設定キー、
/agents エンドポイント、context.agents API はリリース間で変更される可能性があります。[[agents]] テーブルが 1 つ以上存在するまでは無効です。
認識されないキーは生成にそのまま渡されるため、
temperature や top_p はそのまま記述できます。
エージェント定義は起動時に検証されます — モデル参照・ツール名・プロンプトファイルに誤りがあるとサーバーが停止します。
モデル、ツール、session、エンドポイント、CLI、セキュリティモデルについては Agents を参照してください。
次のステップ
ワークスペースバインディング
サーバーを BRICKS ワークスペースとペアリングして認証を有効化します。
LAN 自動検出
Foundation デバイスが LAN 上でサーバーを見つける仕組み。