How to Customize or Fine-Tune Terax AI Models

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): Defines the static MODELS array, PROVIDERS mapping, pricing tiers, and default context windows (MODEL_CONTEXT_LIMITS).
• Preferences Store (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), and context overrides.
• Runtime Resolution (src/modules/ai/store/chatStore.ts and 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.

To change models via the UI, the 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, which writes to persistent storage and emits a change event via emitKeysChanged().

At runtime, AiMiniWindow.tsx reads the selection via useChatStore((s) => s.selectedModelId) and resolves it through getModel() in config.ts.

// 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 (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().

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), 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. 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 and can be imported into scripts or custom plugins:

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.
• 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, 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. 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 (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. 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 and references the capability flags defined alongside each model entry in src/modules/ai/config.ts.

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