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

> Easily set up OpenMAIC for local development using Ollama. Follow this guide to configure the Ollama daemon, keyless provider, model routing, and run the development server for seamless local AI deployment.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/provider-config.ts) and model resolution logic in [`resolve-model.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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](https://ollama.com) and pull your desired model:

```bash
ollama pull llama3.3

```

Verify the daemon is listening:

```bash
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.

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

```

The system explicitly identifies Ollama as keyless in [`lib/server/provider-config.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

```

Or in a `.env` file:

```env
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:

```bash
pnpm install
pnpm dev

```

The server reads `MODEL_ROUTES`, resolves the provider as Ollama through [`resolve-model.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/config-validation.test.ts), ensuring keyless providers bypass authentication checks.

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

```bash
pnpm test

```

The SSRF guard tests in [`tests/server/ssrf-guard.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:**

```bash
ollama pull deepseek-r1

```

**Configure settings.json:**

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

```

**Create .env:**

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

```

**Test with a client request:**

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings-validation.ts), resolution logic in [`lib/server/resolve-model.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/resolve-model.ts), and security tests in [`tests/server/ssrf-guard.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/provider-config.ts), Ollama is included in the `keylessProviders` set. The validation logic in [`lib/store/settings-validation.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.