How to Configure OpenMAIC for Local Development with Ollama: Complete Setup Guide

To configure OpenMAIC for local development with Ollama, start the Ollama daemon on port 11434, configure the keyless provider settings with the base URL, route models using the ollama:<model> syntax in your environment variables, and run the development server.

OpenMAIC from the THU-MAIC repository supports local LLM inference through Ollama, eliminating the need for external API keys during development. This guide shows you how to wire the Ollama daemon into OpenMAIC's provider system using the actual source implementation, including the keyless provider handling in provider-config.ts and model resolution logic in resolve-model.ts.

Prerequisites

Before configuring OpenMAIC, ensure you have Ollama installed and running locally. The Ollama HTTP API must be accessible at http://localhost:11434 (the default port).

Install Ollama from ollama.com and pull your desired model:

ollama pull llama3.3

Verify the daemon is listening:

curl http://localhost:11434/api/tags

Step-by-Step Configuration

Start the Ollama Server

The Ollama daemon runs locally and exposes a REST API on port 11434. Start the server and ensure it remains running in the background while you develop.

ollama serve

By default, this binds to 127.0.0.1:11434. OpenMAIC will communicate with this endpoint using the /v1 path prefix.

Configure the Ollama Provider

OpenMAIC stores provider configurations in JSON settings. According to the validation logic in lib/store/settings-validation.ts, Ollama is treated as a keyless provider, meaning you do not need an API key.

Create or edit your settings file to include the Ollama base URL:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1"
    }
  }
}

The system explicitly identifies Ollama as keyless in lib/server/provider-config.ts within the keylessProviders set. This bypasses API key validation checks while still enforcing SSRF protection via validateUrlForSSRF (see tests/server/ssrf-guard.test.ts for the security test coverage).

Route Models to Ollama

OpenMAIC resolves model identifiers using the format provider:model_name. The resolution logic in lib/server/resolve-model.ts parses strings like ollama:llama3.3 and routes requests to the corresponding provider.

Set the MODEL_ROUTES environment variable to map the default route to your local Ollama model:

export MODEL_ROUTES='{"default":"ollama:llama3.3"}'

Or in a .env file:

MODEL_ROUTES='{"default":"ollama:llama3.3"}'

This tells the server to forward all completion requests to the llama3.3 model running on your local Ollama instance.

Launch the Development Server

With the provider configured and environment variables set, start the OpenMAIC development server. The repository uses pnpm for package management:

pnpm install
pnpm dev

The server reads MODEL_ROUTES, resolves the provider as Ollama through resolve-model.ts, and forwards API calls to http://localhost:11434/v1.

Verification and Testing

Once running, verify the integration works end-to-end. The test suite includes specific validations for Ollama configuration in tests/server/config-validation.test.ts, ensuring keyless providers bypass authentication checks.

Run the test suite to confirm Ollama-related cases pass:

pnpm test

The SSRF guard tests in tests/server/ssrf-guard.test.ts specifically validate that internal Ollama hostnames (including localhost and ollama.internal) are permitted while blocking external SSRF attempts.

Example: Complete Local Setup

Here is a complete working example for a TypeScript development environment:

Pull the model:

ollama pull deepseek-r1

Configure settings.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1"
    }
  }
}

Create .env:

MODEL_ROUTES='{"default":"ollama:deepseek-r1"}'
PORT=3000

Test with a client request:

import { createClient } from '@openmaic/client'

const client = createClient({
  baseUrl: 'http://localhost:3000',
})

async function testLocalModel() {
  const response = await client.chat({
    model: 'ollama:deepseek-r1',
    messages: [{ role: 'user', content: 'Explain quantum computing' }],
  })
  console.log(response.choices[0].message.content)
}

testLocalModel()

Summary

• Ollama is keyless: The provider-config.ts file explicitly lists Ollama in keylessProviders, requiring no API key configuration.
• Base URL format: Always use http://localhost:11434/v1 (with the /v1 suffix) in your provider settings.
• Model routing: Use the syntax ollama:<model_name> in MODEL_ROUTES to route requests through the local daemon.
• Security: The validateUrlForSSRF function allows local Ollama endpoints while protecting against server-side request forgery.
• File references: Configuration validation lives in lib/store/settings-validation.ts, resolution logic in lib/server/resolve-model.ts, and security tests in tests/server/ssrf-guard.test.ts.

Frequently Asked Questions

Does OpenMAIC require an API key for Ollama?

No. According to the source code in lib/server/provider-config.ts, Ollama is included in the keylessProviders set. The validation logic in lib/store/settings-validation.ts explicitly skips API key checks for Ollama, making it ideal for local development without external credentials.

What URL format should I use for the Ollama base URL?

Use http://localhost:11434/v1 (or your custom host with the /v1 path). The /v1 suffix is required because OpenMAIC communicates with Ollama's OpenAI-compatible API endpoint. The SSRF protection in tests/server/ssrf-guard.test.ts validates these internal URLs while blocking external requests.

How does OpenMAIC route requests to specific Ollama models?

OpenMAIC uses the resolve-model.ts module to parse model strings. When you specify ollama:llama3.3 in MODEL_ROUTES, the system extracts ollama as the provider and llama3.3 as the model name, then constructs the appropriate request URL for the local daemon.

Can I use multiple Ollama models simultaneously?

Yes. You can define multiple routes in MODEL_ROUTES by mapping different keys to different ollama:<model> strings. For example: {"code":"ollama:codellama","chat":"ollama:llama3.3"}. The resolution logic handles each route independently while sharing the single Ollama base URL configuration.

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