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:

$OLLAMA_CONTEXT_LENGTH=32768 ollama serve

In another terminal, pull the model:

$ollama pull qwen2.5:1.5b

Add the connection:

{
  "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. Select the connection, then start fx:

$fx provider local

$fx

Connect a hosted endpoint

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

{
  "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:

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:

$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 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.