How Fabric's REST API Handles Ollama Compatibility: A Complete Technical Guide

Fabric's REST API provides full Ollama compatibility by exposing three HTTP endpoints—/api/tags, /api/version, and /api/chat—when started with the --serveOllama flag, translating Ollama-formatted requests into Fabric's internal pattern-based chat pipeline and streaming responses in NDJSON format.

The danielmiessler/fabric project implements a dedicated Ollama compatibility layer that transforms the tool into a drop-in replacement for an Ollama server. When enabled, Fabric's REST API morphs its pattern-based AI infrastructure to accept standard Ollama client requests, allowing seamless integration with existing Ollama ecosystems while leveraging Fabric's advanced plugin system.

Enabling Ollama Compatibility Mode

To activate the compatibility layer, launch Fabric with the --serveOllama flag defined in internal/cli/flags.go (line 76). This flag instructs the server to register Ollama-style routes alongside Fabric's native endpoints.

fabric --serveOllama --address :11434

The ServeOllama function in internal/server/ollama.go (lines 191-210) initializes a Gin router and binds three specific handlers that mirror Ollama's API contract, listening on the port specified by --address (defaulting to :11434).

Ollama-Compatible Endpoint Mapping

When compatibility mode is active, Fabric exposes the following endpoints that replicate core Ollama functionality:

• GET /api/tags – Implemented by ollamaTags (lines 228-254), returns available Fabric patterns as Ollama model objects
• GET /api/version – Inline handler returning the Fabric server version
• POST /api/chat – Implemented by ollamaChat (lines 59-165), handles chat completions with streaming support

These endpoints accept standard Ollama request payloads and return responses in the exact format expected by Ollama clients, including the Open WebUI and Ollama CLI tools.

The Chat Endpoint: Request-to-Response Pipeline

The ollamaChat handler serves as the core translation engine, converting Ollama protocol requests into Fabric's internal ChatRequest format and managing bidirectional streaming.

Parsing Ollama-Style Payloads

Incoming POST requests to /api/chat are unmarshaled into the OllamaRequestBody struct defined at lines 50-55 of internal/server/ollama.go. This structure captures:

• model: The requested pattern name (e.g., summarize:latest)
• messages: Standard chat message arrays with role and content
• options: Configuration parameters including num_ctx for context length
• variables: Pattern variables for dynamic template substitution

Fabric normalizes variable inputs by accepting them either at the top-level variables field or nested inside options["variables"], merging both into a map[string]string (lines 85-106).

Pattern Resolution and Variable Forwarding

The handler extracts the underlying Fabric pattern by splitting the requested model name on the : delimiter (lines 14-15), stripping the :latest suffix that Ollama clients append. It then constructs a ChatRequest containing:

• The resolved pattern name
• Validated context length from num_ctx
• Merged variables map

Using buildFabricChatURL (lines 95-130), the handler constructs the internal forwarding target, handling both full URLs (http://host:port) and shortcut notation (:port) to POST the request to Fabric's native /chat endpoint.

Streaming NDJSON Responses

When the request includes "stream": true, Fabric implements Ollama's Server-Sent Events pattern using newline-delimited JSON (NDJSON). The writeOllamaResponse function (lines 33-50) serializes each response chunk into an OllamaResponse struct and flushes it to the Gin response writer.

After the upstream stream terminates, buildFinalOllamaResponse (lines 66-86) emits a final chunk with "done": true and timing metadata (total_duration, eval_duration), ensuring compatibility with Ollama client expectations.

Configuration Validation and Error Handling

Fabric's compatibility layer includes robust input validation to prevent malformed requests from reaching the core engine.

Context Length Handling with num_ctx

The parseOllamaNumCtx function (lines 86-115) validates the optional num_ctx parameter, which controls the model context window. This parser handles:

• Numeric integers and JSON numbers
• String representations of numbers
• Overflow protection against unreasonably large values (exceeding math.MaxInt32)

Validation failures return HTTP 400 errors with descriptive JSON messages in Ollama's standard error format: {"error": "invalid num_ctx value"}.

Practical Usage Examples

List Available Patterns as Ollama Models

curl -s http://localhost:11434/api/tags | jq .

This returns Fabric patterns formatted as Ollama model objects:

{
  "models": [
    {
      "name": "summarize:latest",
      "model": "summarize:latest",
      "details": {
        "families": ["fabric"],
        "family": "fabric"
      }
    }
  ]
}

Non-Streaming Chat Completion

curl -X POST http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "summarize:latest",
    "messages": [{"role": "user", "content": "Explain containerisation benefits"}],
    "options": {"num_ctx": 2048}
  }' | jq .

Streaming Request with Variables

curl -N -X POST http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "extract_wisdom:latest",
    "messages": [{"role": "user", "content": "Long text here..."}],
    "stream": true,
    "variables": {"language": "english"}
  }'

The stream emits NDJSON lines compatible with Ollama clients:

{"model":"extract_wisdom:latest","created_at":"2024-11-25T12:07:58Z","message":{"role":"assistant","content":"Key insight 1"},"done":false}
{"model":"extract_wisdom:latest","created_at":"2024-11-25T12:07:59Z","message":{"role":"assistant","content":"Key insight 2"},"done":true}

Summary

• Activation: Use the --serveOllama flag to enable compatibility mode, which registers three Ollama-standard endpoints in internal/server/ollama.go.
• Protocol Translation: The ollamaChat handler converts Ollama JSON payloads into Fabric's native ChatRequest format, handling pattern names, variables, and context lengths.
• Streaming Support: Fabric replicates Ollama's NDJSON streaming protocol through writeOllamaResponse, ensuring real-time compatibility with Ollama clients.
• Validation: The parseOllamaNumCtx function provides类型-safe parsing of the num_ctx option with overflow protection.
• Drop-in Replacement: Existing Ollama clients can connect to Fabric without code changes, treating Fabric patterns as Ollama models.

Frequently Asked Questions

What is Fabric's Ollama compatibility mode?

Fabric's Ollama compatibility mode is a server configuration activated by the --serveOllama flag that exposes three HTTP endpoints (/api/tags, /api/version, /api/chat) mimicking the Ollama REST API. This allows Fabric to accept requests from standard Ollama clients while internally routing them through Fabric's pattern-based AI pipeline.

How does Fabric handle Ollama's streaming responses?

When a client sends "stream": true in the request body, Fabric's ollamaChat handler forwards the internal chat response as newline-delimited JSON (NDJSON) chunks. Each chunk is wrapped in an OllamaResponse struct by writeOllamaResponse and flushed immediately to the client, concluding with a final "done": true marker generated by buildFinalOllamaResponse.

Can I use existing Ollama clients with Fabric without modification?

Yes. Any client designed for Ollama—including the official CLI, Open WebUI, or LangChain Ollama integrations—can connect to Fabric when running in compatibility mode on port 11434. Clients treat Fabric patterns (like summarize:latest) as standard Ollama models and can use standard Ollama request formats including the num_ctx and variables options.

What configuration options are supported in the Ollama API format?

Fabric supports the standard model, messages, and stream parameters, plus the Ollama-specific options object which can contain num_ctx (context window size) and variables (pattern template variables). The parseOllamaNumCtx function validates context length values, while variables can be passed either at the top level of the JSON or inside the options object for maximum client compatibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}