---
title: "Custom model connections"
description: "Connect fx to Ollama, vLLM, OpenRouter, and compatible endpoints."
canonical_url: https://fx.sh/docs/configure-fx/custom-model-connections
markdown_url: https://fx.sh/docs/configure-fx/custom-model-connections.md
---

# Custom model connections

Connect fx to an OpenAI-compatible Chat Completions endpoint. A named connection defines the endpoint, authentication, and optional model limits.

Connections belong in the top level of `~/.fx/settings.json`.

## Connect Ollama

Start Ollama with a 32K context window:

```bash
OLLAMA_CONTEXT_LENGTH=32768 ollama serve
```

In another terminal, pull the model:

```bash
ollama pull qwen2.5:1.5b
```

Add the connection:

```json
{
  "provider": "local",
  "providers": {
    "local": {
      "protocol": "openai-chat-completions",
      "base_url": "http://localhost:11434/v1",
      "auth": { "type": "none" },
      "model_metadata": {
        "qwen2.5:1.5b": {
          "context_window": 32768,
          "max_output_tokens": 2048,
          "supports_tool_use": true
        }
      }
    }
  },
  "models": {
    "local": "qwen2.5:1.5b"
  }
}
```

The `context_window` must match [Ollama's context setting](https://docs.ollama.com/context-length). Select the connection, then start fx:

```bash
fx provider local
```

```bash
fx
```

## Connect a hosted endpoint

For OpenRouter, vLLM, or another endpoint that accepts bearer authentication:

```json
{
  "provider": "openrouter",
  "providers": {
    "openrouter": {
      "protocol": "openai-chat-completions",
      "base_url": "https://openrouter.ai/api/v1",
      "auth": {
        "type": "bearer",
        "env": "OPENROUTER_API_KEY"
      }
    }
  },
  "models": {
    "openrouter": "openai/gpt-4.1-mini"
  }
}
```

Set your key and start fx:

```sh
export OPENROUTER_API_KEY="your-api-key"
fx
```

## Connection fields

| Field | Description | Required |
| --- | --- | --- |
| `protocol` | Must be `openai-chat-completions`. | Yes |
| `base_url` | API prefix. fx appends `/chat/completions`. | Yes |
| `auth` | `{ "type": "none" }` or bearer authentication from an environment variable. | Yes |
| `tool_choice_mode` | `omit` by default; use `send` when the server supports tool-choice controls. | No |
| `reviewer_model` | Model used for automatic permission reviews. Defaults to the selected model. | No |
| `model_metadata` | Limits and capabilities for known model IDs. | No |

Connection names begin with a letter and can contain letters, digits, underscores, or hyphens. `gateway`, `codex`, and `grok` are reserved. Base URLs require HTTPS except for loopback addresses.

### Model metadata

| Field | Description |
| --- | --- |
| `context_window` | Context limit used for automatic compaction. |
| `max_output_tokens` | Maximum response length in tokens. |
| `supports_tool_use` | Records whether the model supports function tools. |
| `supports_vision` | Enable image input for a model that supports it. |

`fx models` lists IDs declared in `model_metadata`. You can still select another ID, but the endpoint must recognize it. Without a known context window, fx cannot calculate its automatic compaction threshold.

## Select a connection

`fx provider <name>` saves the selection. Use environment variables for one process:

```bash
FX_PROVIDER=local FX_MODEL=qwen2.5:1.5b fx ask "Read README.md"
```

Project `.fx.json` files cannot define or select custom connections. A private workspace entry in `~/.fx/settings.json` can select one, while its definition remains at the top level.

## Compatibility

Custom connections support streaming text, reasoning, and function tools through Chat Completions. The server must provide the chat template and tool or reasoning parser required by its model.

Image input requires `supports_vision: true` in the model's metadata. Gateway search, credit checks, and vision fallback are unavailable. The adapter does not support custom authentication headers or provider-specific reasoning controls.

Normal [permission rules](https://fx.sh/docs/configure-fx/permissions.md) still apply. In `auto` mode, reviews use the connection's `reviewer_model`, or its selected model when none is set.

Use `fx status --json` to check the selected endpoint and model. If fx reports a missing credential, set the variable named by `auth.env`. For an HTTP error, check the endpoint's response.

---

[Browse all fx documentation](https://fx.sh/llms.txt)