# How to Customize or Fine-Tune Terax AI Models

> Learn how to customize or fine-tune Terax AI models. Configure providers, endpoints, model IDs, and context limits in the preferences store for complete control.

- Repository: [Crynta/terax-ai](https://github.com/crynta/terax-ai)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Terax AI does not include a built-in training pipeline, but you can fully customize which model it uses and tune its runtime behavior by configuring providers, endpoints, model IDs, and context limits in the preferences store.**

Terax AI is designed with a model-agnostic architecture that separates the model catalog from runtime selection, allowing you to swap providers or point to your own fine-tuned servers without recompiling the application. This guide explains how to customize or fine-tune Terax AI models using the configuration layers defined in the `crynta/terax-ai` repository.

## Understanding the Configuration Architecture

The codebase separates model management into three distinct layers that work together at runtime:

- **Model Catalog** ([`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts)): Defines the static `MODELS` array, `PROVIDERS` mapping, pricing tiers, and default context windows (`MODEL_CONTEXT_LIMITS`).
- **Preferences Store** ([`src/modules/settings/store.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/settings/store.ts)): Persists user selections including `defaultModelId`, custom endpoints, API keys (via the OS keyring in [`src/modules/ai/lib/keyring.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/keyring.ts)), and context overrides.
- **Runtime Resolution** ([`src/modules/ai/store/chatStore.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/store/chatStore.ts) and [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts)): Resolves the selected model ID to a concrete endpoint using `resolveModel()` and `getModel()`.

## Selecting a Different Default Model

The default chat model is stored under the `defaultModelId` key in the preferences store, with a fallback defined by `DEFAULT_MODEL_ID` in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts).

To change models via the UI, the [`ModelsSection.tsx`](https://github.com/crynta/terax-ai/blob/main/ModelsSection.tsx) component renders a dropdown that lists every model with a **speed capability ≥ 4** (the autocomplete-eligible set). When you select a model, the UI invokes `setDefaultModel()` imported from [`src/modules/settings/store.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/settings/store.ts), which writes to persistent storage and emits a change event via `emitKeysChanged()`.

At runtime, [`AiMiniWindow.tsx`](https://github.com/crynta/terax-ai/blob/main/AiMiniWindow.tsx) reads the selection via `useChatStore((s) => s.selectedModelId)` and resolves it through `getModel()` in [`config.ts`](https://github.com/crynta/terax-ai/blob/main/config.ts).

```typescript
// Programmatically switch the default model
import { setDefaultModel } from "@/modules/settings/store";

await setDefaultModel("claude-sonnet-4-6");
// Subsequent chat requests will use this model immediately

```

## Adding Custom OpenAI-Compatible Endpoints

To integrate a fine-tuned model hosted on your own infrastructure, add a **named OpenAI-compatible endpoint**:

1. Navigate to **Settings → Models → Add provider → OpenAI Compatible**.
2. Enter the **Base URL**, **Model ID**, and optional **Context** limit.
3. Save the configuration.

The UI calls `setCustomEndpoints()` which writes an array of `CustomEndpoint` objects to the store. These endpoints are defined in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts) (lines 23-30) and use the `compat-` prefix to distinguish them from built-in providers.

When making requests, `resolveModel()` detects IDs starting with `compat-` and maps them to your custom endpoint via `getCompatModelInfo()`.

```typescript
import { setCustomEndpoints, setOpenaiCompatibleBaseURL, setOpenaiCompatibleModelId } from "@/modules/settings/store";

// Define a custom endpoint pointing to your fine-tuned model
const myEndpoint = {
  id: "my-finetuned-endpoint",
  name: "Custom Fine-Tuned Server",
  baseURL: "https://my.api/v1",
  modelId: "ft:gpt-4o-mini:my-org:custom:id",
  contextLimit: 128_000,
};

await setCustomEndpoints([myEndpoint]);
await setOpenaiCompatibleBaseURL("https://my.api/v1");
await setOpenaiCompatibleModelId("ft:gpt-4o-mini:my-org:custom:id");

```

## Tuning Runtime Parameters

### Context Window Limits

Every model entry includes an approximate context window in `MODEL_CONTEXT_LIMITS`. For custom endpoints, you can override this via `setOpenaiCompatibleContextLimit()`, which updates the `openai-compatible-context-limit` key in the preferences store.

The UI exposes this in `LocalProviderCard` and `CustomEndpointCard` components (lines 219-228 in [`ModelsSection.tsx`](https://github.com/crynta/terax-ai/blob/main/ModelsSection.tsx)), allowing you to constrain token usage for specific endpoints.

### Autocomplete Model Selection

Terax uses a fast model for inline autocomplete, defined by `DEFAULT_AUTOCOMPLETE_MODEL` in [`config.ts`](https://github.com/crynta/terax-ai/blob/main/config.ts). Change this through the **Autocomplete** row in Settings, which calls `setAutocompleteProvider()` and `setAutocompleteModelId()` to update the store.

## Programmatic Customization Outside the UI

All configuration functions are exported from [`src/modules/settings/store.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/settings/store.ts) and can be imported into scripts or custom plugins:

```typescript
import {
  setDefaultModel,
  setCustomEndpoints,
  setOpenaiCompatibleContextLimit,
} from "@/modules/settings/store";

// Batch configuration for enterprise deployment
await setDefaultModel("gpt-4o");
await setOpenaiCompatibleContextLimit(200_000);

const endpoints = [
  { id: "prod-1", name: "Production", baseURL: "https://api.internal/v1", modelId: "ft-model-1", contextLimit: 32000 },
  { id: "prod-2", name: "Backup", baseURL: "https://api-backup.internal/v1", modelId: "ft-model-2", contextLimit: 32000 },
];

await setCustomEndpoints(endpoints);

```

These calls update the OS keyring (for credentials) and local storage (for preferences) immediately, taking effect for subsequent AI requests without restarting the application.

## Limitations of On-Device Fine-Tuning

**Terax AI currently does not support local training or fine-tuning pipelines.** The architecture is deliberately inference-only. To use a customized model, you must either:

- Select a different pre-packaged model from the `MODELS` catalog in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts).
- Host your fine-tuned model on an OpenAI-compatible server (such as LM Studio, vLLM, or OpenRouter) and register it as a custom endpoint.

This design keeps the client lightweight while allowing unlimited flexibility through external model hosting.

## Summary

- **Model Selection**: Change the active model using `setDefaultModel()` in [`src/modules/settings/store.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/settings/store.ts), which updates `defaultModelId` in the preferences store.
- **Custom Endpoints**: Add OpenAI-compatible endpoints with `setCustomEndpoints()` to integrate self-hosted or fine-tuned models using the `compat-` ID prefix.
- **Runtime Tuning**: Adjust context limits via `setOpenaiCompatibleContextLimit()` and autocomplete behavior via `setAutocompleteModelId()`.
- **No Local Training**: Terax AI supports customization through configuration and external endpoints, but does not include training infrastructure.

## Frequently Asked Questions

### Can I train or fine-tune a model directly inside Terax AI?

No. Terax AI does not include training capabilities or LoRA fine-tuning pipelines. To use a customized model, you must fine-tune it using external tools (such as OpenAI's fine-tuning API or Hugging Face libraries), host it on an OpenAI-compatible server, and then add the endpoint in Terax via `setCustomEndpoints()`.

### How does Terax AI store my API keys and model preferences?

API keys are stored securely in the OS keyring using the abstraction layer in [`src/modules/ai/lib/keyring.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/keyring.ts). Other preferences—including model IDs, custom endpoints, and context limits—are persisted as JSON in local storage through the typed setters in [`src/modules/settings/store.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/settings/store.ts) (lines 215-652).

### What is the difference between `getModel()` and `resolveModel()`?

`getModel()` retrieves static model metadata from the `MODELS` catalog in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts). `resolveModel()` handles dynamic resolution at runtime, mapping the selected model ID (including custom `compat-` IDs) to the appropriate provider configuration and endpoint URL, checking against `customEndpoints` stored in user preferences.

### Why do some models show "speed capability" requirements in the UI?

The UI filters the model dropdown to show only models with a speed capability rating ≥ 4 when selecting autocomplete providers, ensuring that inline suggestions remain low-latency. This logic resides in [`ModelsSection.tsx`](https://github.com/crynta/terax-ai/blob/main/ModelsSection.tsx) and references the capability flags defined alongside each model entry in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts).