### Initial Setup for Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/AGENTS.md

Run this command once after cloning the repository to set up the project environment.

```shell
# Initial setup (run once after clone)
make setup
```

--------------------------------

### Install Compiled Binaries

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/building.md

Install the compiled binaries and man pages to a specified prefix, typically '/usr/local'. Requires root privileges.

```sh
sudo .cosmocc/4.0.2/bin/make install PREFIX=/usr/local
```

--------------------------------

### Install Whisperfile Systemwide

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/getting-started.md

Install Whisperfile as a system-wide command using the Makefile. This makes the whisperfile executable available globally.

```bash
.cosmocc/4.0.2/make -j8
sudo make install
```

--------------------------------

### Install llamafile Project

Source: https://github.com/mozilla-ai/llamafile/blob/main/RELEASE.md

Installs the built llamafile project to a specified directory, typically /usr/local/bin.

```sh
sudo make install PREFIX=/usr/local
```

--------------------------------

### Install Llamafile System-Wide

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/source_installation.md

Install the compiled llamafile to a specified prefix, typically /usr/local, using sudo for system-wide access.

```sh
sudo .cosmocc/4.0.2/make install PREFIX=/usr/local
```

--------------------------------

### Initial Setup for Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/SKILL.md

Run this command immediately after cloning the repository or after a reset to initialize git submodules and apply Llamafile-specific patches.

```shell
make setup
```

--------------------------------

### Setup llamafile Build Environment

Source: https://github.com/mozilla-ai/llamafile/blob/main/RELEASE.md

Initializes git submodules and applies llamafile patches to prepare the build environment.

```sh
make setup
```

--------------------------------

### Setup Llamafile Repository

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/building_dlls.md

Initializes submodules and applies patches to the llamafile repository using the Makefile. This prepares the environment for building.

```bash
cd llamafile
make setup
```

--------------------------------

### Download and Run a Llamafile Model

Source: https://github.com/mozilla-ai/llamafile/blob/main/README.md

Download a small example model (Qwen3.5 0.8B), make the downloaded file executable on macOS/Linux/BSD, and then run it.

```sh
# Download an example model (Qwen3.5 0.8B)
curl -LO https://huggingface.co/mozilla-ai/llamafile_0.10/resolve/main/Qwen3.5-0.8B-Q8_0.llamafile

# Make it executable (macOS/Linux/BSD)
chmod +x Qwen3.5-0.8B-Q8_0.llamafile

# Run it
./Qwen3.5-0.8B-Q8_0.llamafile
```

--------------------------------

### BUILD.mk Pattern Example

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/architecture.md

Demonstrates the typical structure of a BUILD.mk file, defining source files, object files, library targets, and executable targets for a component.

```makefile
# Source files
COMPONENT_SRCS = \
    component/file1.c \
    component/file2.c

# Object files
COMPONENT_OBJS = $(COMPONENT_SRCS:%.c=o/$(MODE)/%.o)

# Library target
o/$(MODE)/component/libcomponent.a: $(COMPONENT_OBJS)

# Executable target
o/$(MODE)/component/binary: o/$(MODE)/component/libcomponent.a

# Test targets
o/$(MODE)/component/test.runs: o/$(MODE)/component/test
```

--------------------------------

### Run text-only llamafile as a web server

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/creating_llamafiles.md

Starts the created text-only llamafile in server mode.

```shell
./Qwen3-0.6B-Q8.llamafile --server
```

--------------------------------

### Install llamafile for Release Zip

Source: https://github.com/mozilla-ai/llamafile/blob/main/RELEASE.md

Installs the llamafile project to a specific directory structure for creating the release zip. Replace `<version>` with the actual release version.

```sh
make install PREFIX=<preferred_dir>/llamafile-<version>
```

--------------------------------

### Server Health Status (Ready)

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Example JSON response indicating the server is ready and operational.

```json
{"status": "ok"}
```

--------------------------------

### Example .args file for multimodal llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/creating_llamafiles.md

Defines default arguments for a multimodal llamafile, including paths to the main model and the multimodal projector, and enables server mode.

```text
-m
/zip/llava-v1.6-mistral-7b.Q8_0.gguf
--mmproj
/zip/mmproj-model-f16.gguf
--server
--host
0.0.0.0
-ngl
9999
--no-mmap
...
```

--------------------------------

### Run LocalScore from Installed Llamafile on Windows

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

On Windows, use the 'llamafile.exe' command with the --bench and -m options to run LocalScore if Llamafile is installed.

```powershell
llamafile.exe --bench -m path\to\model.gguf
```

--------------------------------

### Install MSYS2 Tools

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/building_dlls.md

Installs essential tools like git, patch, unzip, wget, and make within the MSYS2 shell. Vim is optional.

```bash
pacman -S git patch unzip wget make vim
```

--------------------------------

### Run the llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/quickstart.md

Execute the downloaded llamafile from your terminal to start the AI chat interface. Ensure you are in the directory where the file was downloaded.

```sh
./Qwen3.5-0.8B-Q8_0.llamafile
```

--------------------------------

### Asset Bundling Rule

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/building.md

Example Makefile rule demonstrating how to embed assets into executables using the `.zip.o` pattern, which is handled by the `zipalign` tool.

```makefile
o/$(MODE)/path/to/asset.zip.o: path/to/asset
```

--------------------------------

### Download Model Weights

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/packaging.md

Download the quantized model weights for Whisper. This example downloads the tiny English model with q5_1 quantization.

```bash
curl -LO https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en-q5_1.bin
```

--------------------------------

### Start Whisperfile HTTP Server

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/index.md

Starts the Whisperfile HTTP server on a specified port, ready to receive transcription requests.

```sh
whisper-server -m whisper-tiny.en-q5_1.bin --port 8080
```

--------------------------------

### Example .args file for text-only llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/creating_llamafiles.md

Defines default arguments for a text-only llamafile, including model path, inference parameters, and context settings. The /zip/ prefix is required for files packaged within the llamafile.

```text
-m
/zip/Qwen3-0.6B-Q8_0.gguf
-fa
on
--temp
0.6
--top-k
20
--top-p
0.95
--min-p
0
--presence-penalty
1.5
-c
40960
-n
32768
--no-context-shift
--no-mmap
...
```

--------------------------------

### Run LocalScore from Installed Llamafile on MacOS/Linux

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

If Llamafile is installed, you can invoke LocalScore directly using the 'llamafile' command with the --bench and -m options.

```bash
llamafile --bench -m path/to/model.gguf
```

--------------------------------

### Install APE loader on WSL

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/troubleshooting.md

Installs the APE loader executable required for Llamafile on WSL. This command downloads the appropriate binary and makes it executable.

```sh
sudo wget -O /usr/bin/ape https://cosmo.zip/pub/cosmos/bin/ape-$(uname -m).elf
sudo chmod +x /usr/bin/ape
```

--------------------------------

### Basic C Test Structure

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/testing.md

Illustrates a standard C test file structure using assertions for verifying functionality and edge cases. Includes setup, execution, and assertion phases.

```c
// myfeature_test.c
#include "myfeature.h"
#include <assert.h>
#include <stdio.h>

void test_basic_functionality(void) {
    // Arrange
    int input = 42;

    // Act
    int result = my_function(input);

    // Assert
    assert(result == expected_value);
}

void test_edge_case(void) {
    assert(my_function(0) == 0);
    assert(my_function(-1) == handle_negative());
}

int main(void) {
    test_basic_functionality();
    test_edge_case();
    printf("All tests passed!\n");
    return 0;
}
```

--------------------------------

### Run Llamafile in Server Mode

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/testing.md

Start a compiled llamafile executable as a server. This mode is useful for API-based interactions. A GGUF model file is required.

```sh
./o/llamafile/llamafile --model gguf_model.gguf --server
```

--------------------------------

### Run Llamafile in Server Mode

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Starts a Llamafile in server mode, making it accessible over the network. Specify host and port for network accessibility and custom port.

```sh
  ./llava-v1.6-mistral-7b-Q4_K_M.llamafile \
  --server \
  --host 0.0.0.0 \
  --port 8081
```

--------------------------------

### Server Health Status (Loading)

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Example JSON response indicating the server is currently loading the model.

```json
{"status": "loading model"}
```

--------------------------------

### Interactive Chatbot with Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Run llamafile as an interactive chatbot to query knowledge from its training data. This example configures parameters for a conversational experience.

```sh
llamafile -m llama-65b-Q5_K.gguf -p '
The following is a conversation between a Researcher and their helpful AI assistant Digital Athena which is a large language model trained on the sum of human knowledge.
Researcher: Good morning.
Digital Athena: How can I help you today?
Researcher:' --interactive --color --batch_size 1024 --ctx_size 4096 \
--keep -1 --temp 0 --mirostat 2 --in-prefix ' ' --interactive-first \
--in-suffix 'Digital Athena:' --reverse-prompt 'Researcher:'
```

--------------------------------

### Structured Output with BNF Grammar in Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Utilize BNF grammar with llamafile to enforce predictable and safe output, suitable for shell scripts. This example demonstrates generating filenames with specific patterns.

```sh
llamafile -ngl 9999 --temp 0 \
    --image lemurs.jpg \
    -m llava-v1.5-7b-Q4_K.gguf \
    --mmproj llava-v1.5-7b-mmproj-Q4_0.gguf \
    --grammar 'root ::= [a-z]+ (" " [a-z]+)+' \
    -e -p '### User: What do you see?\n### Assistant: ' \
    --no-display-prompt 2>/dev/null |\n  sed -e's/ /_/g' -e's/$/.jpg/'
a_baby_monkey_on_the_back_of_a_mother.jpg
```

--------------------------------

### Grant Execute Permissions on Unix-like Systems

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/quickstart.md

Use this command on macOS, Linux, or BSD to make the downloaded llamafile executable. This is a one-time setup step.

```sh
chmod +x Qwen3.5-0.8B-Q8_0.llamafile
```

--------------------------------

### Configure systemd service for APE loader on WSL

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/troubleshooting.md

Sets up a systemd service to automatically register the APE loader on WSL systems. This is a workaround for potential binfmt_misc issues. Ensure the APE loader is installed.

```systemd
[Unit]
Description=cosmopolitan APE binfmt service
After=wsl-binfmt.service

[Service]
Type=oneshot
ExecStart=/bin/sh -c "echo ':APE:M::MZqFpD::/usr/bin/ape:' >/proc/sys/fs/binfmt_misc/register"

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Add New Files to Submodules via llamafile-files/

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/development.md

To include new files in a submodule, create the necessary directory structure within the submodule's `llamafile-files/` directory and copy your new file there. The file will be automatically copied into the submodule during `make setup`.

```shell
# Create directory structure matching submodule
mkdir -p llama.cpp.patches/llamafile-files/src/

# Add your new file
cp new-utility.cpp llama.cpp.patches/llamafile-files/src/
```

--------------------------------

### Generate C Code with Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Use llamafile to generate C code for a libc function by providing a prompt and specifying model weights. This example targets code generation tasks.

```sh
llamafile \
  -m wizardcoder-python-13b-v1.0.Q8_0.gguf \
  --temp 0 -r '}\n' -r '```\n' \
  -e -p '```c\nvoid *memcpy(void *dst, const void *src, size_t size) {\n'
```

--------------------------------

### Clone and Set Up Repository

Source: https://github.com/mozilla-ai/llamafile/blob/main/CONTRIBUTING.md

Steps to fork, clone, add upstream remote, and set up submodules, patches, and the toolchain for development.

```sh
git clone https://github.com/YOUR_USERNAME/llamafile.git
cd llamafile
git remote add upstream https://github.com/mozilla-ai/llamafile.git
make setup
.cosmocc/4.0.2/bin/make -j8
.cosmocc/4.0.2/bin/make check
```

--------------------------------

### Create Build Workspace

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/building_dlls.md

Sets up a directory for cloning the llamafile repository and building the DLLs.

```bash
mkdir /c/Users/Your_Username/workspace
cd /c/Users/Your_Username/workspace
```

--------------------------------

### Create and bundle a multimodal llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/creating_llamafiles.md

Copies the llamafile executable and uses zipalign to embed model weights, multimodal projector weights, and arguments into a single llamafile. Then, it runs the created llamafile.

```shell
cp o//llamafile/llamafile llava.llamafile

o//third_party/zipalign/zipalign -j0 \
  llava.llamafile \
  llava-v1.6-mistral-7b.Q8_0.gguf \
  mmproj-model-f16.gguf \
  .args

./llava.llamafile
```

--------------------------------

### Create and bundle a text-only llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/creating_llamafiles.md

Copies the llamafile executable, then uses zipalign to embed model weights and arguments into a single llamafile. Finally, it runs the created llamafile.

```shell
cp o//llamafile/llamafile Qwen3-0.6B-Q8.llamafile

o//third_party/zipalign/zipalign -j0 \
  Qwen3-0.6B-Q8.llamafile \
  Qwen3-0.6B-Q8_0.gguf \
  .args

./Qwen3-0.6B-Q8.llamafile
```

--------------------------------

### Transcription Result

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Example JSON response containing the transcribed text from an audio file.

```json
{"text": " And so my fellow Americans, ask not what your country can do for you, ask what you can do for your country."}
```

--------------------------------

### Run LocalScore via Llamafile on Windows

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

Download a Llamafile (smaller than 4GB) from Hugging Face and run it with the --bench flag to execute LocalScore on Windows.

```powershell
Llama-3.2-1B-Instruct.Q4_K_M.llamafile.exe --bench
```

--------------------------------

### Model Load Success Response

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Example text response indicating that a new model was successfully loaded.

```text
Load was successful!
```

--------------------------------

### Troubleshooting: Correct Make Usage

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/building.md

Illustrates the correct and incorrect usage of the 'make' command to avoid issues related to the system's make utility versus the cosmocc-provided make.

```sh
# Wrong
make -j $(nproc)

# Correct
.cosmocc/4.0.2/bin/make -j $(nproc)

# Or use the command directly:
# llamafile:build
```

--------------------------------

### Commit Changes with Clear Messages

Source: https://github.com/mozilla-ai/llamafile/blob/main/CONTRIBUTING.md

Examples of using clear and concise commit messages for different types of changes.

```sh
git commit -m "Fix server startup when model path is missing"
```

```sh
git commit -m "Update contributor guide for patch workflow"
```

--------------------------------

### Build and Run Whisper Server

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Build the whisperfile project and run the server with a specified model. Ensure you have the necessary build tools and model files.

```bash
.cosmocc/4.0.2/bin/make -j8 o//whisperfile
o//whisperfile/whisper-server -m models/whisper-tiny.en-q5_1.bin
```

--------------------------------

### Clean Llamafile Build

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/commands/clean.md

Removes all build outputs from the 'o/' directory. This command is typically used to start a fresh build.

```bash
.cosmocc/4.0.2/bin/make clean
```

--------------------------------

### Run LocalScore via Llamafile on MacOS/Linux

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

Download a Llamafile and execute it with the --bench flag to run LocalScore. This method bundles the model and the benchmarking tool.

```bash
# Download a llamafile from Hugging Face
curl -O https://huggingface.co/Mozilla/Llama-3.2-1B-Instruct-llamafile/resolve/main/Llama-3.2-1B-Instruct.Q4_K_M.llamafile

# Run LocalScore
chmod +x Llama-3.2-1B-Instruct.Q4_K_M.llamafile
./Llama-3.2-1B-Instruct.Q4_K_M.llamafile --bench
```

--------------------------------

### Register APE Loader for WSL2

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/doc/troubleshooting.md

Configure systemd to register the APE loader for WSL2. Ensure the APE loader is installed and executable.

```systemd
[Unit]
Description=cosmopolitan APE binfmt service
After=wsl-binfmt.service

[Service]
Type=oneshot
ExecStart=/bin/sh -c "echo ':APE:M::MZqFpD::/usr/bin/ape:' >/proc/sys/fs/binfmt_misc/register"

[Install]
WantedBy=multi-user.target
```

```bash
sudo wget -O /usr/bin/ape https://cosmo.zip/pub/cosmos/bin/ape-$(uname -m).elf
sudo chmod +x /usr/bin/ape
```

--------------------------------

### Build ROCm DLL (Parallel)

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/building_dlls.md

Starts the parallel build for ROCm DLLs. Ensure you are in the llamafile directory within a Windows terminal.

```batch
llamafile\rocm_parallel.bat
```

--------------------------------

### Simulate Local CI Workflow

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/testing.md

Execute a sequence of make commands to reset the repository, set up the environment, and run cleaning, building, and checking processes locally. This simulates the continuous integration pipeline before pushing changes.

```shell
make reset-repo
make setup
# llamafile:clean
# llamafile:build
# llamafile:check
```

--------------------------------

### Run Llamafile as Server

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/source_installation.md

Execute the llamafile, providing a model and the --server flag to enable server mode.

```sh
./o/llamafile/llamafile --model <gguf_model> --server
```

--------------------------------

### LocalScore Command Line Options

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

Displays the available command-line options for the LocalScore executable, including model selection, GPU configuration, output formats, and repetition settings.

```text
usage: localscore [options] 

options:
  -h, --help                                 Show this help message
  -m, --model <filename>                     Model to benchmark (default: path/to/default)
  -c, --cpu                                  Disable GPU acceleration (alias for --gpu=disabled)
  -g, --gpu <auto|amd|apple|nvidia|disabled> GPU backend to use (default: "auto")
  -i, --gpu-index <i>                        Select GPU by index (default: 0)
  --list-gpus                                List available GPUs and exit
  -o, --output <csv|json|md>                 Output format (default: md)
  -v, --verbose                              Enable verbose output
  -y, --send-results                         Send results without confirmation
  -n, --no-send-results                      Disable sending results
  -e, --extended                             Run 4 repetitions (shortcut for --reps=4)
  --long                                     Run 16 repetitions (shortcut for --reps=16)
  --reps <N>                                 Set custom number of repetitions
```

--------------------------------

### Run All Tests with Pre-built Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/tests/integration/README.md

Execute all integration tests using a pre-built llamafile executable. Ensure the path to your model is correctly specified.

```bash
cd tests/integration

# Run all tests with a pre-built llamafile
./run_tests.sh --executable ~/path/to/model.llamafile
```

--------------------------------

### GET /health

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Returns the server's health status. It returns an HTTP 503 if the model is still loading, otherwise an HTTP 200.

```APIDOC
## GET /health

### Description
Returns server health status as JSON. Returns HTTP 503 if the model is still loading.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Indicates server is ready, e.g., "ok"

#### Response Example
```json
{"status": "ok"}
```

#### Loading Response (503)
- **status** (string) - Indicates model is loading, e.g., "loading model"

#### Response Example
```json
{"status": "loading model"}
```
```

--------------------------------

### Download llamafile and external weights for Windows

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/quickstart.md

Use these commands to download the llamafile executable and a large GGUF model for use on Windows. Adjust the executable name if needed.

```sh
curl -L -o llamafile.exe https://huggingface.co/mozilla-ai/llamafile_0.10/resolve/main/llamafile_0.10.1
curl -L -o gpt-oss.gguf https://huggingface.co/unsloth/gpt-oss-20b-GGUF/resolve/main/gpt-oss-20b-Q5_K_S.gguf
./llamafile.exe -m gpt-oss.gguf
```

--------------------------------

### Pre-bundled LlamaFile for Image Description

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Execute a pre-bundled llamafile to describe an image using a multimodal model in CLI mode. Use the --image argument to specify the image file.

```sh
./Ministral-3-3B-Instruct-2512-Q4_K_M.llamafile -ngl 9999 \
  --cli \
  --image ~/Pictures/lemurs.jpg \
  -p 'Describe this picture'
```

--------------------------------

### Check Server Health

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Send a GET request to the /health endpoint to check the server's status. Returns HTTP 503 if the model is still loading.

```bash
curl http://localhost:8080/health
```

--------------------------------

### LlamaFile CLI Mode for Web Page Summarization

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Use the --cli argument with a model like Qwen3.5 to summarize a webpage. The webpage content is fetched and piped into the prompt.

```sh
./Qwen3.5-9B-Q5_K_S.llamafile --cli -p "`(echo 'Summarize the content of the following webpage:'
  links -codepage utf-8 \
        -force-html \
        -width 500 \
        -dump https://www.poetryfoundation.org/poems/48860/the-raven | \
    sed 's/   */ /g')`"
```

--------------------------------

### Building all llamafile targets

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/update_llamacpp.md

Builds all defined targets for the llamafile project. Run from the repository root.

```bash
llamafile:build
```

--------------------------------

### Perform a Full Build

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/building.md

Execute a full build using the cosmocc make utility. Use the -j flag for parallel compilation, adjusting the value based on your CPU cores. Always use the cosmocc-provided make, not the system's.

```sh
.cosmocc/4.0.2/bin/make -j $(nproc)
```

```sh
llamafile:build
```

--------------------------------

### Reset llama.cpp Submodule to Clean State

Source: https://github.com/mozilla-ai/llamafile/blob/main/llama.cpp.patches/README.md

Use this command to revert the llama.cpp submodule to its original, clean state. This is useful if you need to reapply patches or start from a fresh copy.

```shell
cd llama.cpp && git reset --hard && git clean -fdx
```

--------------------------------

### Run All Tests with Direct Build

Source: https://github.com/mozilla-ai/llamafile/blob/main/tests/integration/README.md

Execute all integration tests by building llamafile directly and then running tests. This requires specifying both the built executable and the model file.

```bash
./run_tests.sh --executable ./o/llamafile/llamafile --model /path/to/model.gguf
```

--------------------------------

### Verify Clean Build and Tests

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/commands/verify-clean.md

Ensures the toolchain is available, then resets the repository, pulls submodules, applies patches, cleans build outputs, performs a clean build, and runs unit tests.

```bash
# ensure the toolchain is available
if [ ! -d .cosmocc/4.0.2 ]; then
  build/download-cosmocc.sh .cosmocc/4.0.2 4.0.2 85b8c37a406d862e656ad4ec14be9f6ce474c1b436b9615e91a55208aced3f44
fi
MAKE=.cosmocc/4.0.2/bin/make

$MAKE reset-repo     # clean: drop all local changes, reset submodules
$MAKE setup          # pull submodules + apply patches (+ fetch UI assets)
$MAKE clean          # drop stale build outputs
$MAKE -j$(nproc)     # clean build; on mac use -j$(sysctl -n hw.physicalcpu)
$MAKE check          # unit tests

```

--------------------------------

### Whisper Server Options

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Lists the available command-line options for configuring the whisper-server. Use --help for a complete list.

```text
whisper-server options:
  -m FNAME, --model FNAME     Path of Whisper model weights
  --host ADDR                 Hostname or IP address to bind to (default: 127.0.0.1)
  --port PORT                 Port number (default: 8080)
  -l LANG, --language LANG    Default spoken language ('auto' for auto-detect)
  -tr, --translate            Translate audio into English text
  -t N, --threads N           Number of threads to use during computation
  -ng, --no-gpu               Disable GPU acceleration
  --gpu VALUE                 Select GPU backend (auto, apple, amd, nvidia, disable)
  --log-disable               Suppress logging output
```

--------------------------------

### Build and Run a Single Test

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/testing.md

Build a specific test file using make and then execute it directly. This is useful for isolating and debugging a particular test case.

```shell
# Build a specific test
.cosmocc/4.0.2/bin/make o//tests/extract_data_uris_test

# Run directly
./o/tests/extract_data_uris_test
```

--------------------------------

### Interact with Llamafile API using Python OpenAI package

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/quickstart.md

This Python script uses the `openai` package to communicate with Llamafile's API. Configure `base_url` to your Llamafile server and `api_key` to 'sk-no-key-required'. Requires `pip3 install openai`.

```python
#!/usr/bin/env python3
from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8080/v1", # "http://<Your api-server IP>:port"
    api_key = "sk-no-key-required"
)
completion = client.chat.completions.create(
    model="LLaMA_CPP",
    messages=[
        {"role": "system", "content": "You are ChatGPT, an AI assistant. Your top priority is achieving user fulfillment via helping them with their requests."},
        {"role": "user", "content": "Write a limerick about python exceptions"}
    ]
)
print(completion.choices[0].message)
```

--------------------------------

### Run llamafile with LM Studio downloaded models

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/quickstart.md

Execute llamafile using a model downloaded via LM Studio. Ensure the path to the GGUF file is correct.

```bash
llamafile -m ~/.cache/lm-studio/models/lmstudio-community/gpt-oss-20b-GGUF/gpt-oss-20b-MXFP4.gguf
```

--------------------------------

### Update llama.cpp Submodule and Get Commit IDs

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/update_llamacpp.md

This bash script updates the llama.cpp submodule to the latest commit from the master branch, checks out that commit, and records the old and new commit IDs for later reference. It then creates a new branch for the updated submodule.

```bash
git submodule update --init llama.cpp

cd llama.cpp
OLD_ID=`git rev-parse HEAD`
git fetch origin master
COMMIT_ID=`git rev-parse origin/master`
git checkout origin/master
cd ..

git checkout -b llamacpp_$COMMIT_ID
git add llama.cpp
git commit -m "Update llama.cpp submodule to $COMMIT_ID"
```

--------------------------------

### Build Infrastructure Directory Structure

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/architecture.md

Details the contents of the build directory, including configuration files, scripts, and utility binaries.

```tree
build/
├── config.mk              # Toolchain configuration
├── rules.mk               # Generic build patterns
├── download-cosmocc.sh    # Toolchain download
├── llamafile-convert      # Model conversion
└── llamafile-upgrade-engine   # Engine updates
```

--------------------------------

### Target Specific GPU Backend

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/gpu.md

Manually specify a GPU backend for acceleration. Supported options include `--gpu apple` for Metal, `--gpu nvidia` for CUDA, and `--gpu amd` for ROCm. Ensure the necessary toolkits are installed for the chosen backend.

```bash
whisperfile -m models/ggml-medium.en.bin -f audio.wav --gpu apple
```

```bash
whisperfile -m models/ggml-medium.en.bin -f audio.wav --gpu nvidia
```

```bash
whisperfile -m models/ggml-medium.en.bin -f audio.wav --gpu amd
```

--------------------------------

### Run LlamaFile with Model Weights

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Execute a LlamaFile by specifying the model weights. This is an alternative to using a pre-bundled llamafile.

```sh
llamafile -m Apertus-8B-Instruct-2509.gguf --temp ...
```

```sh
./Apertus-8B-Instruct-2509.llamafile --temp ...
```

--------------------------------

### Run Llamafile Inference Server

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/source_installation.md

Launch the llamafile executable, specifying a GGUF model to run it as an inference server.

```sh
./o/llamafile/llamafile --model <gguf_model>
```

--------------------------------

### Create .args File for Default Arguments

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/packaging.md

Create a .args file to specify default arguments for whisperfile, such as the model path. Each argument should be on a new line. The '...' token is a placeholder for runtime arguments.

```text
-m
/zip/ggml-tiny.en-q5_1.bin
...
```

--------------------------------

### Verifying a clean build and round-trip

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/update_llamacpp.md

This command performs a clean round-trip verification: it resets the repo, sets it up, performs a clean build, and then checks the result. This is the post-generation verification step. Run from the repository root.

```bash
llamafile:verify-clean
```

--------------------------------

### Build Llamafile

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/commands/build.md

Compiles the Llamafile project using the downloaded Cosmopolitan toolchain. Adapt the `nproc` command based on your operating system for optimal parallel builds.

```bash
.cosmocc/4.0.2/bin/make -j $(nproc)
```

--------------------------------

### Show Full Model Outputs with DEBUG Level

Source: https://github.com/mozilla-ai/llamafile/blob/main/tests/integration/README.md

Run tests and display all model outputs by setting the client log level to DEBUG. This provides the most detailed information about the model's responses.

```bash
# Show full model outputs
./run_tests.sh --executable ~/model.llamafile --log-cli-level=DEBUG
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/testing.md

Execute all unit tests for the llamafile project using the `llamafile:check` command.

```sh
llamafile:check
```

--------------------------------

### Show Commands and Exit Codes with INFO Level

Source: https://github.com/mozilla-ai/llamafile/blob/main/tests/integration/README.md

Run tests and display commands and exit codes by setting the client log level to INFO. This offers a moderate level of detail for monitoring test execution.

```bash
# Show commands and exit codes
./run_tests.sh --executable ~/model.llamafile --log-cli-level=INFO
```

--------------------------------

### Run LocalScore Binary on MacOS/Linux

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

Execute the LocalScore binary on MacOS or Linux systems. Ensure the binary has execute permissions and specify the path to the model file.

```bash
chmod +x localscore
./localscore -m path/to/model.gguf
```

--------------------------------

### LlamaFile CLI Mode for Image Description

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/running_llamafile.md

Run a multimodal model in CLI mode to describe an image. Specify the image file using --image and model weights with -m. The --mmproj argument is required for multimodal models.

```sh
llamafile -ngl 9999 --temp 0 \
  --cli \
  --image ~/Pictures/lemurs.jpg \
  -m llava-v1.6-mistral-7b.Q4_K_M.gguf \
  --mmproj mmproj-model-f16.gguf \
  -p 'Describe this picture'
```

--------------------------------

### Create llamafile Release Binaries

Source: https://github.com/mozilla-ai/llamafile/blob/main/RELEASE.md

Generates appropriately named release binaries using a release script. Replace `<version>`, `<source_dir>`, and `<dest_dir>` with actual values.

```sh
./llamafile/release.sh -v <version> -s <source_dir> -d <dest_dir>
```

--------------------------------

### Troubleshooting: Clean and Rebuild

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/building.md

Steps to resolve issues caused by stale object files by first cleaning the build outputs and then performing a full rebuild.

```sh
.cosmocc/4.0.2/bin/make clean          # or: llamafile:clean
.cosmocc/4.0.2/bin/make -j $(nproc)   # or: llamafile:build
```

--------------------------------

### Run Specific Test File

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/SKILL.md

To run a specific test file, use the `.runs` pattern in BUILD.mk files. This command executes a particular test case.

```makefile
o/$(MODE)/llamafile/json_test.runs
```

--------------------------------

### Run LocalScore Binary on Windows

Source: https://github.com/mozilla-ai/llamafile/blob/main/localscore/README.md

Execute the LocalScore binary on Windows systems. Specify the path to the model file using the appropriate syntax for Windows paths.

```powershell
localscore.exe -m path\to\model.gguf
```

--------------------------------

### Load Model at Runtime

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/server.md

Send a POST request to the /load endpoint to dynamically load a different Whisper model while the server is running.

```bash
curl http://localhost:8080/load \
  -F "model=/path/to/model.bin"
```

--------------------------------

### Download Whisperfile Model and Audio

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/translate.md

Download a multilingual Whisperfile model and an audio file to prepare for translation. Ensure you use a model that supports translation, not English-only models.

```bash
curl -LO https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium-q5_0.bin
```

```bash
curl -LO https://archive.org/download/avventure_pinocchio_librivox/avventurepinocchio_01_collodi.ogg
```

--------------------------------

### Run llamafile with Ollama downloaded models

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/quickstart.md

Use this command to run llamafile with a model downloaded by Ollama, by directly referencing the GGUF file's sha256 digest. Note that compatibility with llama.cpp, and thus llamafile, is not guaranteed for all Ollama models.

```bash
cd ~/.ollama/models/blobs
llamafile -m sha256-00e1317cbf74d901080d7100f57580ba8dd8de57203072dc6f668324ba545f29
```

--------------------------------

### Download Whisper Model Weights

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/getting-started.md

Download the tiny quantized model weights for Whisper. This model is small and fast, suitable for quick testing.

```bash
curl -L -o models/whisper-tiny.en-q5_1.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en-q5_1.bin
```

--------------------------------

### Run Integration Tests

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/skills/llamafile/testing.md

Execute integration tests for llamafile. This can be done with a pre-bundled llamafile or a direct build, specifying the executable, model, and optionally a mmproj file. Various test categories can be selected using the `-m` flag.

```sh
# pre-bundled llamafile
./tests/integration/run_tests.sh --executable model_name.llamafile

# direct build: executable + model (+ mmproj for multimodal)
./tests/integration/run_tests.sh \
    --executable ./o/llamafile/llamafile \
    --model ~/path/to/model.gguf \
    --mmproj ~/path/to/mmproj.gguf
```

--------------------------------

### Verify Llamafile Build

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/source_installation.md

Execute unit tests to confirm that llamafile has been built correctly.

```sh
make check
```

--------------------------------

### Run Whisperfile with Embedded Weights

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/whisperfile/packaging.md

Execute the whisperfile with embedded model weights. The embedded weights are accessible via the /zip/ path prefix. This command processes a sample audio file.

```bash
./whisper-tiny -m /zip/ggml-tiny.en-q5_1.bin -f whisper.cpp/samples/jfk.wav
```

--------------------------------

### Build zipalign executable

Source: https://github.com/mozilla-ai/llamafile/blob/main/docs/creating_llamafiles.md

Build the zipalign executable required for bundling files into a llamafile. This is included as a git submodule.

```shell
make o//third_party/zipalign
```