Packaged Butter product

The public artifact is the Rust-hosted butter executable built without the developer-cli feature. The engine/backend implementation remains an archive detail; all three archives expose the same four commands.

User workflow

Installation is not published yet. Until the signed archives and waffuru.ai release site exist, scripts/install.sh exits with an unpublished-release message and changes nothing.

Once installed, the default path is intentionally one command:

$ butter serve
Selected model: Qwen3.8-27B · Qwen model / bartowski artifact · Q4_K_M GGUF · 17.7 GB
Why: automatic selection · <device recipe> · <measured usable memory>
Storage: ~/.butter/models/qwen3.8-27b-q4_k_m/Qwen3.8-27B-Q4_K_M.gguf

The exact recipe text varies by backend and measured memory. Before a network transfer, Butter prints the model, recipe, measured usable memory, and storage target. The final two-line ready state adds qualification, backend, cache, context, and concurrency. Butter downloads to a .part, resumes that file on the next run, rehashes from byte zero, checks both the full SHA-256 and 17,772,537,440-byte size, atomically publishes the weights, and only then listens. A hang-up cancels an active download, prefill, or decode.

The complete public command surface is:

$ butter serve [--model ID] [--context auto|TOKENS] [--concurrency auto|N]
$ butter version [--json|--licenses]
$ butter report --out DIR [--telemetry-preview]
$ butter cost [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--compare NAME] [--json]

butter --version and butter -V are aliases for butter version; they report the same offline release, backend, recipe, artifact, and pin identity. --json may follow either long form.

serve is the only command that listens. The other commands are local and non-interactive. --unsafe-memory-overcommit is available only with exact --context TOKENS and --concurrency N; it prints a freeze/lost-work warning and does not weaken artifact verification.

Files on disk

Butter uses one durable root, ~/.butter by default or BUTTER_HOME when set:

Path	Purpose
config.toml	Optional strict operator configuration; unknown keys fail closed.
models/<catalog-id>/<artifact>.gguf	Verified release-catalog weights.
selection.json	Last selected model, recipe, and provenance.
verification.json	Exact artifact verification identity.
ledger.jsonl	One append-only local request ledger.
last-error.json	Last categorized error and a human remedy.

butter report copies scrubbed diagnostics into the directory named by the user. Prompts, completions, tool data, secrets, usernames, hostnames, client addresses, and raw paths do not belong in that folder or telemetry.

Native runner builds

Run one job on each matching runner:

scripts/package-product.sh darwin-arm64-metal
scripts/package-product.sh linux-x64-cuda
scripts/package-product.sh linux-arm64-cuda

After collecting all three ZIPs, sign the digest manifest with the offline release key:

BUTTER_SIGNING_KEY=/secure/release-private.pem scripts/release-checks.sh dist

Publish the three ZIPs, SHA256SUMS, and SHA256SUMS.sig under the same release directory. The private key never enters the repository or an archive.

release-checks.sh also refuses to sign while the launch catalog entry remains Compatible. Closing WH-003 on the exact shipping pin/backend is the separate evidence required before changing that entry to Butter Verified; packaging tests cannot promote it.

The checked-in install.sh is a fail-closed placeholder until the release site exists at waffuru.ai. Platform selection, signature verification, and atomic binary replacement will land with the website; the placeholder never pretends that an installation succeeded.

Distributed scope

The launch recipes in this package are single-device recipes. Butter’s optional NCCL backend establishes a same-stream F32 all-reduce primitive and bounded peer-failure behavior; it does not yet provide tensor-parallel model placement, model-level collectives, or capture-safe communicator ownership. The package must not infer multi-Spark execution merely because NCCL is present.

A future distributed recipe needs its own exact artifact placement, world/rank bootstrap, NCCL runtime and library identity, transport proof, collective sequence, memory envelope, model correctness, failure, and end-to-end performance evidence. Until then, automatic selection remains single-device. See the NCCL backend contract.

Operator configuration

The default file is ~/.butter/config.toml; BUTTER_HOME relocates the whole durable tree. A basic SMB configuration remains small:

[serve]
host = "0.0.0.0"
port = 8000
api_key_env = "BUTTER_API_KEY"
context = 131072
concurrency = 1
queue = 4
cache_policy = "auto"
offline = false

[telemetry]
sink_url = "https://collector.example/v1/traces"
authorization_env = "BUTTER_OTLP_AUTH"

[cost]
comparison = "openai-gpt-5-mini"

Non-loopback binding fails unless the named API-key environment variable is present. Secrets are never stored in TOML or copied into butter report. DO_NOT_TRACK prevents creation of the telemetry queue or any export request.

cache_policy = "auto" prefers standard KV. It may select Aura only when the embedded catalog contains an exact validated Aura recipe for the selected pin, backend, device class, context, and concurrency. This release contains no such recipe, so explicit aura fails closed and a long-context request uses standard KV only when the measured budget fits.