Instructions to use jashepp/Equinox-31B-i1-MXFP4-GGUF with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="jashepp/Equinox-31B-i1-MXFP4-GGUF")
messages = [
    {"role": "user", "content": "Who are you?"},
]
pipe(messages)

# Load model directly
from transformers import AutoModel
model = AutoModel.from_pretrained("jashepp/Equinox-31B-i1-MXFP4-GGUF", device_map="auto")

Notebooks
Google Colab
Kaggle
Local Apps Settings

llama.cpp

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with llama.cpp:

Install (macOS, Linux)

curl -LsSf https://llama.app/install.sh | sh
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4
# Run inference directly in the terminal:
llama cli -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4
# Run inference directly in the terminal:
llama cli -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Use pre-built binary

# Download pre-built binary from:
# https://github.com/ggerganov/llama.cpp/releases
# Start a local OpenAI-compatible server with a web UI:
./llama-server -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4
# Run inference directly in the terminal:
./llama-cli -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Build from source code

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build -j --target llama-server llama-cli
# Start a local OpenAI-compatible server with a web UI:
./build/bin/llama-server -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4
# Run inference directly in the terminal:
./build/bin/llama-cli -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Use Docker

docker model run hf.co/jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

LM Studio
Jan

vLLM

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "jashepp/Equinox-31B-i1-MXFP4-GGUF"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "jashepp/Equinox-31B-i1-MXFP4-GGUF",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

SGLang

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "jashepp/Equinox-31B-i1-MXFP4-GGUF" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "jashepp/Equinox-31B-i1-MXFP4-GGUF",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "jashepp/Equinox-31B-i1-MXFP4-GGUF" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "jashepp/Equinox-31B-i1-MXFP4-GGUF",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Ollama
How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with Ollama:
```
ollama run hf.co/jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4
```
Unsloth Desktop

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with Pi:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Configure the model in Pi

# Install Pi:
npm install -g @earendil-works/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Docker Model Runner
How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with Docker Model Runner:
```
docker model run hf.co/jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4
```

Lemonade

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Run and chat with the model

lemonade run user.Equinox-31B-i1-MXFP4-GGUF-MXFP4

List all available models

lemonade list

Hermes Agent

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with Hermes Agent:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Run Hermes

hermes

Atomic Chat

OpenClaw

How to use jashepp/Equinox-31B-i1-MXFP4-GGUF with OpenClaw:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4

Configure OpenClaw

# Install OpenClaw:
npm install -g openclaw@latest
# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "jashepp/Equinox-31B-i1-MXFP4-GGUF:MXFP4" \
  --custom-provider-id llama-cpp \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

Run OpenClaw

openclaw agent --local --agent main --message "Hello from Hugging Face"

💎 Equinox-31B - Custom Mixed Precision GGUFs with Imatrix

Equinox draws its name from the balance between extremes. Trained on a balanced blend of Wayfarer 2's unforgiving dark adventures and Hearthfire's quiet slice-of-life storytelling, Equinox is equally at home in perilous dungeons and candlelit conversations.
Equinox 31B was trained with two epochs of SFT (Supervised Fine-Tuning) on top of Gemma 4 31B Instruct.

This repository contains custom, highly optimized, multi-tier mixed precision GGUF weights for LatitudeGames/Equinox-31B.

📄 GGUF Files

In order of quality:

Filename	Size	Quants
Equinox-31B-MXFP4_Q8_0_F16-Imatrix.gguf	22.9 GB	MXFP4_MOE + Q8_0 + F16
Equinox-31B-MXFP4_Q6_K_Q8_0-Imatrix.gguf	19.5 GB	MXFP4_MOE + Q6_K + Q8_0
Equinox-31B-MXFP4_Q8_0-Imatrix.gguf	17.7 GB	MXFP4_MOE + Q8_0
Equinox-31B-MXFP4_Q6_K-Imatrix.gguf	17.1 GB	MXFP4_MOE + Q6_K
Equinox-31B-MXFP4-Only-Imatrix.gguf	16.3 GB	MXFP4_MOE Only

Updated 2026-07-07:

Used larger datasets for imatrix
Added Equinox-31B-MXFP4-Only-Imatrix.gguf

Updated 2026-06-28:

Used a new combined/blended imatrix
MXFP4_Q8_0 & MXFP4_Q6_K
- Renamed to use model-quants-imatrix style naming
- Corrected --tensor-type regex

📊 Importance Matrix (Imatrix)

Expand to view datasets & details

The following datasets were used for the imatrix:

I am currently remaking this imatrix with 2048 ctx, 3000 chunks, with smaller chunks & sets of text
Old/Current: Custom Target Matrix (2048 ctx with 600 chunks), with all of the following:
- ~1.5MB of my own story/writing data
- eaddario/imatrix-calibration - tools_medium
- Crownelius/Opus-4.5-WritingStyle-1000x-formatted-fixed
- froggeric/imatrix - tiny.txt
- eaddario/imatrix-calibration - text_en_medium
- SimpleStories/SimpleStories

🔍 Precision Matrix & Flavor Variations

Standard global quantization presets (like stock MXFP4) compress the backbone layers uniformly, which degrades the quality of models.
This repository provides multiple distinct manual configuration layouts to balance precision and memory constraints:

1. The Tri-Quant Hybrid Flavor (MXFP4 + Q8_0 + F16)

Equinox-31B-MXFP4_Q8_0_F16-Imatrix.gguf - Designed for maximum quality preservation, this layout implements a strict 3-Tier Precision Matrix:

Tier 1 (Core - F16 Precision): token_embd.weight - Protects the critical input/output vocabulary mappings. Dramatically prevents text degradation.
Tier 2 (Backbone - Q8_0 Precision): attn_q, attn_k, attn_v, attn_output, attn_qkv - All core attention layers. Keeps the model's primary attention mechanism high quality.
Tier 3 (Dense FFN - MXFP4 Precision): ffn_down, ffn_gate, ffn_up - Downsamples the massive, heavy feed-forward network layers to hardware-optimized 4-bit microscaling blocks.

2. The Dual-Quant Hybrid Flavor (MXFP4 + Q8_0)

Equinox-31B-MXFP4_Q8_0-Imatrix.gguf - Designed for a slightly leaner memory profile, this layout utilizes 2-Tier Precision:

Tier 1 (Backbone - Q8_0 Precision): Vocabulary embeddings (token_embd), final logit projections (output), layer normalizations, and structural layers fall back to the heavy Q8_0 format.
Tier 2 (Compute Layers - MXFP4 Precision): attn_k, attn_q, attn_output, ffn_down, ffn_gate, ffn_up - The core attention projections and dense feed-forward network blocks are target-quantized directly to MXFP4 to leverage highly optimized hardware kernels.

3. The Tri-Quant Hybrid Flavor (MXFP4 + Q6_K + Q8_0)

Equinox-31B-MXFP4_Q6_K_Q8_0-Imatrix.gguf - Designed for a tighter VRAM footprint while preserving quality, this layout implements a strict 3-Tier Precision Matrix:

Tier 1 (Core - Q8_0 Precision): token_embd.weight - Keeps the critical input/output vocabulary mappings. Lessens the text degradation.
Tier 2 (Backbone - Q6_K Precision): attn_q, attn_k, attn_v, attn_output, attn_qkv - All core attention layers. Keeps the model's primary attention mechanism at decent quality.
Tier 3 (Dense FFN - MXFP4 Precision): ffn_down, ffn_gate, ffn_up - Downsamples the massive, heavy feed-forward network layers to hardware-optimized 4-bit microscaling blocks.

4. The Dual-Quant Hybrid Flavor (MXFP4 + Q6_K)

Equinox-31B-MXFP4_Q6_K-Imatrix.gguf - Designed for an even tighter VRAM footprint while preserving the mathematical depth of the logical layers, this layout utilizes 2-Tier Precision:

Tier 1 (Backbone - Q6_K Precision): Vocabulary embeddings (token_embd), final logit projections (output), layer normalizations, and structural layers fall back to the heavy Q6_K format.
Tier 2 (Compute Layers - MXFP4 Precision): attn_k, attn_q, attn_output, ffn_down, ffn_gate, ffn_up - The core attention projections and dense feed-forward network blocks are target-quantized directly to MXFP4 to leverage highly optimized hardware kernels.

5. Bonus Single-Quant (MXFP4)

Equinox-31B-MXFP4-Only-Imatrix.gguf - Using only MXFP4, this shrinks the model down to 16.3 GB. The quality is not the best, but it can still do decent work.

Single Tier (All Layers - MXFP4 Precision): All layers are target-quantized directly to MXFP4, for speed and a low VRAM footprint.

📝 Exact Conversion Details

These files were converted via llama-quantize utilizing the following manual recipe parameters:

Generate Tri-Quant MXFP4_MOE + Q8_0 + F16:

llama-quantize \
  --tensor-type "token_embd\.weight=F16" \
  --tensor-type "blk\..*\.(ffn_down|ffn_gate|ffn_up)\.weight=MXFP4" \
  --imatrix "imatrix.gguf" \
  "Equinox-31B_Unified_BF16.gguf" \
  "Equinox-31B-MXFP4_Q8_0_F16-Imatrix.gguf" \
  Q8_0

Generate Dual-Quant MXFP4_MOE + Q8_0:

llama-quantize \
  --tensor-type "blk\..*\.(attn_k|attn_q|attn_output|ffn_down|ffn_gate|ffn_up)\.weight=MXFP4" \
  --imatrix "Equinox-31B-combined-imatrix.gguf" \
  "Equinox-31B_Unified_BF16.gguf" \
  "Equinox-31B-MXFP4_Q8_0-Imatrix.gguf" \
  Q8_0

Generate Tri-Quant MXFP4_MOE + Q6_K + Q8_0:

llama-quantize \
  --tensor-type "token_embd\.weight=Q8_0" \
  --tensor-type "blk\..*\.(ffn_down|ffn_gate|ffn_up)\.weight=MXFP4" \
  --imatrix "imatrix.gguf" \
  "Equinox-31B_Unified_BF16.gguf" \
  "Equinox-31B-MXFP4_Q6_K_Q8_0-Imatrix.gguf" \
  Q6_K

Generate Dual-Quant MXFP4_MOE + Q6_K:

llama-quantize \
  --tensor-type "blk\..*\.(attn_k|attn_q|attn_output|ffn_down|ffn_gate|ffn_up)\.weight=MXFP4" \
  --imatrix "imatrix.gguf" \
  "Equinox-31B_Unified_BF16.gguf" \
  "Equinox-31B-MXFP4_Q6_K-Imatrix.gguf" \
  Q6_K

Generate Single-Quant MXFP4_MOE:

llama-quantize \
  --tensor-type "token_embd\.weight=MXFP4" \
  --tensor-type "blk\..*\.(attn_k|attn_q|attn_v|attn_output|ffn_down|ffn_gate|ffn_up)\.weight=MXFP4" \
  --imatrix "imatrix.gguf" \
  "Equinox-31B_Unified_BF16.gguf" \
  "Equinox-31B-MXFP4-Only-Imatrix.gguf" \
  MXFP4_MOE

ℹ️ Misc Details

I'm doing this as a side hobby, with my AMD 5900X, 64GB DDR4, RTX 3060 12GB & RTX 5060 Ti 16GB.

I've found this model works best up to 35k context before it starts hallucinating, with it worsening when it reaches 45k, 64k, etc.

It works well for SillyTavern with CharMemory and MessageLimit.
It also works well enough for story-writing analysis.

🤝 Support the Journey

As a passionate developer, I'm always programming, automating, or experimenting with new ideas.
I love building open-source tools, trying out new web tech, and creating things that don't yet exist, including local AI & quantizing models.

I love sharing these creations to give back to the community.
If my projects have saved you time or helped you out, consider supporting my work below!

👉 Support me on Ko-fi