# Model Specs Object Structure (https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/model_specs)

## **Overview**

The `modelSpecs` object helps you provide a simpler UI experience for AI models within your application.

There are 3 main fields under `modelSpecs`:

- `enforce` (optional; default: false)
- `prioritize` (optional; default: true)
- `list` (required)
- `addedEndpoints` (optional)

**Notes:**

- If `enforce` is set to true, model specifications can potentially conflict with other interface settings such as `modelSelect`, `presets`, and `parameters`.
- The `list` array contains detailed configurations for each model, including presets that dictate specific behaviors, appearances, and capabilities.
- If [interface](interface.mdx) fields are not specified in the configuration, having a list of model specs will disable the following interface elements:
  - `modelSelect`
  - `parameters`
  - `presets`
- If you would like to enable these interface elements along with model specs, you can set them to `true` in the `interface` object.

<Callout type="info" title="Managing user-provided API keys with Model Specs">
  When Model Specs disable `modelSelect`, the endpoints dropdown — and the gear icon that opens the **Set API Key** dialog — is hidden. Users can still set or rotate keys for any endpoint configured with `apiKey: "user_provided"` from **Settings → Data controls → API keys**.

  That list is scoped to the endpoints a user can actually reach: the endpoints referenced by your model specs, plus any [`addedEndpoints`](#addedendpoints). When the `agents` endpoint is reachable, it also includes the agent [`allowedProviders`](/docs/configuration/librechat_yaml/object_structure/agents#allowedproviders) (or every configured provider when `allowedProviders` is left unset).
</Callout>

## Example

```yaml filename="modelSpecs"
modelSpecs:
  enforce: true
  prioritize: true
  list:
    - name: 'meeting-notes-gpt4'
      label: 'Meeting Notes Assistant (GPT4)'
      softDefault: true
      description: 'Generate meeting notes by simply pasting in the transcript from a Teams recording.'
      iconURL: 'https://example.com/icon.png'
      showOnLanding: true
      conversation_starters:
        - 'Summarize this meeting transcript'
        - 'Extract action items and owners'
      hideBadgeRow: true
      skills:
        - 'brand-guidelines'
        - 'meeting-notes'
      subagents:
        enabled: true
        allowSelf: true
        agent_ids: []
      preset:
        endpoint: 'azureOpenAI'
        model: 'gpt-4-turbo-1106-preview'
        maxContextTokens: 128000 # Maximum context tokens
        max_tokens: 4096 # Maximum output tokens
        temperature: 0.2
        modelLabel: 'Meeting Summarizer'
        greeting: |
          This assistant creates meeting notes based on transcripts of Teams recordings.
          To start, simply paste the transcript into the chat box.
        promptPrefix: |
          Based on the transcript, create coherent meeting minutes for a business meeting. Include the following sections:
          - Date and Attendees
          - Agenda
          - Minutes
          - Action Items

          Focus on what items were discussed and/or resolved. List any open action items.
          The format should be a bulleted list of high level topics in chronological order, and then one or more concise sentences explaining the details.
          Each high level topic should have at least two sub topics listed, but add as many as necessary to support the high level topic. 

          - Do not start items with the same opening words.

          Take a deep breath and be sure to think step by step.
```

---

## **Top-level Fields**

### enforce

<OptionTable
  options={[
    [
      'enforce',
      'Boolean',
      'Determines whether the model specifications should strictly override other configuration settings.',
      'Setting this to `true` can lead to conflicts with interface options if not managed carefully.',
    ],
  ]}
/>

**Default:** `false`

**Example:**

```yaml filename="modelSpecs / enforce"
modelSpecs:
  enforce: true
```

---

### prioritize

<OptionTable
  options={[
    [
      'prioritize',
      'Boolean',
      'Specifies if model specifications should take priority over the default configuration when both are applicable.',
      'When set to `true`, it ensures that a modelSpec is always selected in the UI. Doing this may prevent users from selecting different endpoints for the selected spec.',
    ],
  ]}
/>

**Default:** `true`

**Example:**

```yaml filename="modelSpecs / prioritize"
modelSpecs:
  prioritize: false
```

---

### addedEndpoints

<OptionTable
  options={[
    [
      'addedEndpoints',
      'Array of Strings',
      'Allows specific endpoints (e.g., "openAI", "google") to be selectable in the UI alongside the defined model specs.',
      'Requires `interface.modelSelect` to be `true`. If this field is used and `interface.modelSelect` is not explicitly set, `modelSelect` will default to `true`.',
    ],
  ]}
/>

**Default:** `[]` (empty list)

**Note:** Must be one of the following:

- `openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock, agents`

**Example:**

```yaml filename="modelSpecs / addedEndpoints"
modelSpecs:
  # ... other modelSpecs fields
  addedEndpoints:
    - openAI
    - google
```

---

### list

**Required**

<OptionTable
  options={[
    [
      'list',
      'Array of Objects',
      'Contains a list of individual model specifications detailing various configurations and behaviors.',
      "Each object in the list details the configuration for a specific model, including its behaviors, appearance, and capabilities related to the application's functionality.",
    ],
  ]}
/>

## **Model Spec (List Item)**

Within each **Model Spec**, or each **list** item, you can configure the following fields:

---

### name

<OptionTable
  options={[
    ['name', 'String', 'Unique identifier for the model.', 'No default. Must be specified.'],
  ]}
/>

**Description:**
Unique identifier for the model.

---

### label

<OptionTable
  options={[
    [
      'label',
      'String',
      'A user-friendly name or label for the model, shown in the header dropdown.',
      'No default. Optional.',
    ],
  ]}
/>

**Description:**
A user-friendly name or label for the model, shown in the header dropdown.

---

### default

<OptionTable
  options={[
    [
      'default',
      'Boolean',
      'Specifies if this model spec is the default selection, to be auto-selected on every new chat.',
      '',
    ],
  ]}
/>

**Description:**  
Specifies if this model spec is the default selection, to be auto-selected on every new chat.

---

### softDefault

<OptionTable
  options={[
    [
      'softDefault',
      'Boolean',
      'Specifies if this model spec should be selected only for first-time users who have not already selected a model, model spec, or agent.',
      '',
    ],
  ]}
/>

**Description:**

Specifies a first-run default without overriding a user's later selections. Use `softDefault` when you want to guide new users to a curated spec while preserving user choice after they pick another model, spec, or agent.

Viewing an older conversation that used a soft-default spec does not re-arm that spec as the user's default after they have made another selection.

If the user's stored selection points to an Agent that no longer resolves, LibreChat re-arms the soft default so a new chat still has a usable selection. A temporary failure to load the Agent list does not clear the stored choice or trigger that fallback.

**Example:**

```yaml filename="modelSpecs / softDefault"
modelSpecs:
  list:
    - name: 'general-assistant'
      label: 'General Assistant'
      softDefault: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### showInMenu

<OptionTable
  options={[
    [
      'showInMenu',
      'Boolean',
      'Controls whether the complete model spec appears in the model selector and client startup configuration.',
      'true',
    ],
  ]}
/>

Set `showInMenu: false` to hide a spec from interactive selection while keeping it available for trusted server-side callers that explicitly send its `name` in the `spec` field. This differs from `showIconInMenu`, which hides only the icon.

```yaml filename="modelSpecs / showInMenu"
modelSpecs:
  list:
    - name: 'api-only-assistant'
      label: 'API-only Assistant'
      showInMenu: false
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### iconURL

<OptionTable
  options={[
    [
      'iconURL',
      'String',
      "URL or a predefined endpoint name for the model's icon in selector, header, and conversation branding.",
      'No default. Optional.',
    ],
  ]}
/>

**Description:**  
URL or a predefined endpoint name for the model's icon in selector, header, and conversation branding. Use `showIconInMenu` and `showIconInHeader` to control where the icon appears.

---

### description

<OptionTable
  options={[
    [
      'description',
      'String',
      'A brief description of the model and its intended use or role, shown in the model selector and optionally on the chat landing.',
      'No default. Optional.',
    ],
  ]}
/>

**Description:**
A brief description of the model and its intended use or role, shown in the model selector. If `showOnLanding` is true, the same description is also shown on the chat landing under the spec label.

Plain text descriptions render as text. Descriptions that start with `<` render through the config HTML sanitizer, allowing safe inline markup and media such as small icons.

---

### conversation_starters

<OptionTable
  options={[
    [
      'conversation_starters',
      'Array of Strings',
      'Suggested starter prompts shown as clickable cards on the chat landing when this model spec is selected.',
      'No default. Optional.',
    ],
  ]}
/>

**Description:**
Conversation starters give users curated first prompts for a model spec. They are shown on the empty chat landing for the selected spec and are especially useful with `showOnLanding` branding. Clicking a starter submits it as the first message of a new conversation.

- A maximum of 4 starters are displayed, matching the agent/assistant limit.
- If the spec's preset points to an agent or assistant that defines its own conversation starters, those take precedence.

**Example:**

```yaml filename="modelSpecs / conversation_starters"
modelSpecs:
  list:
    - name: 'meeting-notes'
      label: 'Meeting Notes'
      showOnLanding: true
      conversation_starters:
        - 'Summarize this meeting transcript'
        - 'Create action items with owners and due dates'
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'
```

---

### showOnLanding

<OptionTable
  options={[
    [
      'showOnLanding',
      'Boolean',
      "Shows this model spec's label and description on the chat landing in place of the default greeting.",
      'showOnLanding: true',
    ],
  ]}
/>

**Default:** `false`

Use this when a curated model spec should brand the first empty-chat screen. Existing model specs are unchanged unless `showOnLanding` is set to `true`.

**Example:**

```yaml filename="modelSpecs / showOnLanding"
modelSpecs:
  list:
    - name: 'branded-assistant'
      label: 'Acme Research'
      description: '<span><img src="/assets/acme.svg" alt="Acme" /> Research with approved sources</span>'
      showOnLanding: true
      iconURL: '/assets/acme.svg'
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'
```

---

### group

<OptionTable
  options={[
    [
      'group',
      'String',
      'Optional group name for organizing model specs in the UI selector. Controls where the spec appears in the menu hierarchy.',
      'No default. Optional.',
    ],
    [
      'groupIcon',
      'String',
      'Optional icon for custom groups. Can be a URL or a built-in endpoint key (e.g., "openAI", "groq"). Only the first spec with a groupIcon in each group is used.',
      'No default. Optional.',
    ],
  ]}
/>

**Description:**
Optional group name for organizing model specs in the UI selector. The `group` field provides flexible control over how model specs are organized:

- **If `group` matches an endpoint name** (e.g., `"openAI"`, `"groq"`): The model spec appears nested under that endpoint in the selector menu
- **If `group` is a custom name** (doesn't match any endpoint): Creates a separate collapsible section with that name. You can optionally use `groupIcon` to set a custom icon for this section (URL or built-in key like `"openAI"`)
- **If `group` is omitted**: The model spec appears as a standalone item at the top level

This feature is particularly useful when you want to add descriptions to models without losing the organizational structure of the selector menu.

---

### hideBadgeRow

<OptionTable
  options={[
    [
      'hideBadgeRow',
      'Boolean',
      'Hides the tool badge row for this model spec in the chat composer.',
      'hideBadgeRow: true',
    ],
  ]}
/>

**Default:** `false`

Use this when a curated model spec should not show the row of tool/capability badges beneath the composer.

**Example:**

```yaml filename="modelSpecs / hideBadgeRow"
modelSpecs:
  list:
    - name: 'general-assistant'
      label: 'General Assistant'
      hideBadgeRow: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

**Example:**

```yaml filename="modelSpecs with group field examples"
modelSpecs:
  list:
    # Example 1: Nested under an endpoint
    # When group matches an endpoint name, the spec appears under that endpoint
    - name: 'gpt-4o-optimized'
      label: 'GPT-4 Optimized'
      description: 'Most capable GPT-4 model with multimodal support'
      group: 'openAI' # Appears nested under the OpenAI endpoint
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

    # Example 2: Custom group section with icon
    # When group is a custom name, it creates a separate collapsible section
    - name: 'coding-assistant'
      label: 'Coding Assistant'
      description: 'Specialized for coding tasks'
      group: 'My Assistants'
      groupIcon: 'https://example.com/icons/assistants.png' # Custom icon for the group
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

    # Multiple specs with the same group name are grouped together
    - name: 'writing-assistant'
      label: 'Writing Assistant'
      description: 'Specialized for creative writing'
      group: 'My Assistants' # Grouped with coding-assistant, uses its icon
      preset:
        endpoint: 'anthropic'
        model: 'claude-sonnet-4'

    # Example 3: Custom group using built-in icon
    - name: 'fast-model'
      label: 'Fast Model'
      group: 'Fast Models'
      groupIcon: 'groq' # Uses built-in Groq icon
      preset:
        endpoint: 'groq'
        model: 'llama3-8b-8192'

    # Example 4: Standalone (no group)
    # When group is omitted, the spec appears at the top level
    - name: 'general-assistant'
      label: 'General Assistant'
      description: 'General purpose assistant'
      # No group field - appears as standalone item at top level
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### showIconInMenu

<OptionTable
  options={[
    [
      'showIconInMenu',
      'Boolean',
      "Controls whether the model's icon appears in the header dropdown menu.",
      '',
    ],
  ]}
/>

**Description:**  
Controls whether the model's icon appears in the header dropdown menu. Defaults to `true`.

---

### showIconInHeader

<OptionTable
  options={[
    [
      'showIconInHeader',
      'Boolean',
      "Controls whether the model's icon appears in the header dropdown button, left of its name.",
      '',
    ],
  ]}
/>

**Description:**  
Controls whether the model's icon appears in the header dropdown button, left of its name. Defaults to `true`.

---

### authType

<OptionTable
  options={[
    [
      'authType',
      'String',
      'Authentication type required for the model spec.',
      'Optional. Possible values: "override_auth", "user_provided", "system_defined"',
    ],
  ]}
/>

**Description:**  
Authentication type required for the model spec. Determines whether authentication is overridden, provided by the user, or defined by the system.

---

### webSearch

<OptionTable
  options={[
    [
      'webSearch',
      'Boolean',
      'Enables web search capability for this model spec.',
      'When true, the model can perform web searches.',
    ],
  ]}
/>

**Description:**  
Enables web search capability for this model spec. When set to `true`, the model can perform web searches to retrieve current information.

**Example:**

```yaml filename="modelSpecs / webSearch"
modelSpecs:
  list:
    - name: 'research-assistant'
      label: 'Research Assistant'
      webSearch: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'
```

---

### fileSearch

<OptionTable
  options={[
    [
      'fileSearch',
      'Boolean',
      'Enables file search capability for this model spec.',
      'When true, the model can search through uploaded files.',
    ],
  ]}
/>

**Description:**  
Enables file search capability for this model spec. When set to `true`, the model can search through and reference uploaded files.

**Example:**

```yaml filename="modelSpecs / fileSearch"
modelSpecs:
  list:
    - name: 'document-analyst'
      label: 'Document Analyst'
      fileSearch: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'
```

---

### executeCode

<OptionTable
  options={[
    [
      'executeCode',
      'Boolean',
      'Enables code execution capability for this model spec.',
      'When true, the model can execute code.',
    ],
  ]}
/>

**Description:**  
Enables code execution capability for this model spec. When set to `true`, the model can execute code in a sandboxed environment.

**Example:**

```yaml filename="modelSpecs / executeCode"
modelSpecs:
  list:
    - name: 'code-assistant'
      label: 'Code Assistant'
      executeCode: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'
```

---

### memory

<OptionTable
  options={[
    [
      'memory',
      'Boolean',
      'Equips the model spec\'s ephemeral agent with memory tools.',
      'false',
    ],
  ]}
/>

Requires configured [User Memory](/docs/features/memory), the endpoint-level `memory` capability, and user memory permissions. When enabled, the model can save or delete structured memories when the user explicitly requests it.

```yaml filename="modelSpecs / memory"
modelSpecs:
  list:
    - name: 'memory-assistant'
      memory: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### askUserQuestion

<OptionTable
  options={[
    [
      'askUserQuestion',
      'Boolean',
      'Lets the model spec pause to ask up to four related questions and resume with the answers.',
      'false',
    ],
  ]}
/>

Requires the endpoint-level `ask_user_question` capability. This is supported in Agent chat runs that provide LibreChat's durable pause/resume flow.

```yaml filename="modelSpecs / askUserQuestion"
modelSpecs:
  list:
    - name: 'interactive-assistant'
      askUserQuestion: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### runInBackground

<OptionTable
  options={[
    [
      'runInBackground',
      'Boolean or Array of Strings',
      'Controls which eligible tools attached to the model spec may run as background tasks.',
      'Unset (background-native code defaults apply)',
    ],
  ]}
/>

Requires the opt-in endpoint-level `run_in_background` capability. With that capability and `executeCode: true`, Code Interpreter execution and shell calls are background-eligible by default. Set `runInBackground: false` or `[]` to opt them out, `true` to enable every eligible tool attached to the spec, or an array of resolved tool IDs to enable only those tools. Selecting `execute_code` or `bash_tool` selects both native code tools; a list that omits them opts them out. Unsupported or misspelled selections are logged.

The model can start an eligible tool and continue working. For saved Agents, supported content-only completions are delivered automatically by default; `check_background_task` remains available for status, control, live artifacts, and recovery. Completed code output and generated files are attached to the original code call. Ordinary execution is process-local and does not survive the loss of its worker process, but a persisted terminal result may be delivered from another replica. Administrators can restore poll-only behavior with [`endpoints.agents.backgroundTasks.completionWakeups: false`](/docs/configuration/librechat_yaml/object_structure/agents#backgroundtasks).

```yaml filename="modelSpecs / runInBackground"
modelSpecs:
  list:
    - name: 'operations-assistant'
      mcpServers: ['operations']
      executeCode: true
      runInBackground:
        - 'execute_code'
        - 'slow_report_mcp_operations'
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### describeIntent

<OptionTable
  options={[
    [
      'describeIntent',
      'Boolean or Array of Strings',
      'Controls which eligible tools stream a model-written intent as their live tool-call label.',
      'Unset (native intent defaults apply)',
    ],
  ]}
/>

Requires the opt-in endpoint-level `tool_intents` capability. Native tools such as web search, file authoring, memory, and supported Code Interpreter tools use intent labels by default while the capability is enabled. Set `describeIntent: true` to enable every eligible tool, or provide resolved tool IDs to enable only those tools and disable labels for everything else. An empty array disables all intent labels for the spec. Omitting the field or setting it to `false` adds no broader selection, so native defaults still apply.

Intent labels are included in tool schemas and therefore add schema tokens to model requests. LibreChat logs selections that are misspelled, unavailable to the spec, or ineligible.

```yaml filename="modelSpecs / describeIntent"
modelSpecs:
  list:
    - name: 'research-assistant'
      webSearch: true
      mcpServers: ['research']
      describeIntent:
        - 'web_search'
        - 'search_mcp_research'
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'
```

---

### mcpServers

<OptionTable
  options={[
    [
      'mcpServers',
      'Array of Strings',
      'List of Model Context Protocol (MCP) server names to enable for this model spec.',
      'Each string should match a configured MCP server name.',
    ],
  ]}
/>

**Description:**  
List of Model Context Protocol (MCP) server names to enable for this model spec. MCP servers extend the model's capabilities with custom tools and resources.

**Example:**

```yaml filename="modelSpecs / mcpServers"
modelSpecs:
  list:
    - name: 'enhanced-assistant'
      label: 'Enhanced Assistant'
      mcpServers:
        - 'filesystem'
        - 'sequential-thinking'
        - 'fetch'
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'
```

---

### skills

<OptionTable
  options={[
    [
      'skills',
      'Boolean or Array of Strings',
      "Controls Skills for this model spec. Use true for the user's active accessible catalog, false to force Skills off, or an array of Skill names as a strict allowlist.",
      'skills: ["brand-guidelines", "code-review"]',
    ],
  ]}
/>

**Description:**

Controls Skills for this model spec when the Agents endpoint Skills capability is available.

- `true`: enables the user's active accessible Skill catalog.
- `false`: disables Skills for this spec.
- Array of Skill names: narrows catalog, manual invocation, and always-apply resolution to the named Skills.

**Example:**

```yaml filename="modelSpecs / skills"
modelSpecs:
  list:
    - name: 'brand-assistant'
      label: 'Brand Assistant'
      skills:
        - 'brand-guidelines'
        - 'approved-claims'
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'
```

---

### subagents

<OptionTable
  options={[
    [
      'subagents.enabled',
      'Boolean',
      'Enables the Subagents capability for ephemeral agents created from this model spec.',
      'enabled: true',
    ],
    [
      'subagents.allowSelf',
      'Boolean',
      'Allows the ephemeral agent to spawn an isolated copy of itself for focused work.',
      'allowSelf: true',
    ],
    [
      'subagents.agent_ids',
      'Array of Strings',
      'Private server-side allowlist of additional agent IDs this model spec may spawn.',
      'agent_ids: []',
    ],
  ]}
/>

**Description:**

Controls Subagents for ephemeral agents created from this model spec. Use this when you want a curated model spec to expose delegation behavior without requiring users to create or select a persisted parent agent.

- `enabled`: adds the subagent spawn tool for this model spec.
- `allowSelf`: lets the ephemeral agent spawn a fresh isolated copy of itself.
- `agent_ids`: allows specific persisted agents as additional subagents. This list is capped by the effective subagents limit, which defaults to 10 and is configurable with [`endpoints.agents.maxSubagents`](/docs/configuration/librechat_yaml/object_structure/agents#maxsubagents). The list remains server-side; startup config sent to clients only includes public `enabled` and `allowSelf` flags.

When model specs are enforced, the model spec's `subagents` settings are authoritative over request payload values.

**Example:**

```yaml filename="modelSpecs / subagents"
modelSpecs:
  list:
    - name: 'research-assistant'
      label: 'Research Assistant'
      subagents:
        enabled: true
        allowSelf: true
        agent_ids: []
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'
```

---

### artifacts

<OptionTable
  options={[
    [
      'artifacts',
      'String | Boolean',
      'Enables the Artifacts capability for this model spec and optionally sets the artifact mode.',
      'Set to `true` to enable with the default mode, `false` or omit to disable, or a specific mode string (e.g., `"default"`) to enable with that mode.',
    ],
  ]}
/>

**Description:**  
Enables the Artifacts capability for this model spec, allowing the model to generate and display interactive artifacts such as React components, HTML, and Mermaid diagrams. When set to `true`, the default artifact mode is used. You can also specify a mode string directly.

**Example:**

```yaml filename="modelSpecs / artifacts"
modelSpecs:
  list:
    - name: 'artifact-assistant'
      label: 'Artifact Assistant'
      artifacts: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'
```

---

### preset

<OptionTable
  options={[
    [
      'preset',
      'Object',
      'Detailed preset configurations that define the behavior and capabilities of the model.',
      'See "Preset Object Structure" below.',
    ],
  ]}
/>

**Description:**  
Detailed preset configurations that define the behavior and capabilities of the model (see Preset Object Structure below).

---

## Preset Fields

The `preset` field for a `modelSpecs.list` item is made up of a comprehensive configuration blueprint for AI models within the system. It is designed to specify the operational settings of AI models, tailoring their behavior, outputs, and interactions with other system components and endpoints.

### System Options

#### endpoint

**Required**

**Accepted Values:**

- `openAI`
- `azureOpenAI`
- `google`
- `anthropic`
- `assistants`
- `azureAssistants`
- `bedrock`
- `agents`

**Note:** If you are using a custom endpoint, the `endpoint` value must match the defined [custom endpoint name](/docs/configuration/librechat_yaml/object_structure/custom_endpoint#name) exactly.

<OptionTable
  options={[
    [
      'endpoint',
      'Enum (EModelEndpoint) or String (nullable)',
      'Specifies the endpoint the model communicates with to execute operations. This setting determines the external or internal service that the model interfaces with.',
      '',
    ],
  ]}
/>

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / endpoint"
preset:
  endpoint: 'openAI'
```

---

#### modelLabel

<OptionTable
  options={[
    [
      'modelLabel',
      'String (nullable)',
      'The label used to identify the model in user interfaces or logs. It provides a human-readable name for the model, which is displayed in the UI, as well as made aware to the AI.',
      'None',
    ],
  ]}
/>

**Default:** `None`

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / modelLabel"
preset:
  modelLabel: 'Customer Support Bot'
```

---

#### greeting

<OptionTable
  options={[
    [
      'greeting',
      'String',
      'A predefined message that is visible in the UI before a new chat is started. This is a good way to provide instructions to the user, or to make the interface seem more friendly and accessible.',
      '',
    ],
  ]}
/>

**Default:** `None`

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / greeting"
preset:
  greeting: 'This assistant creates meeting notes based on transcripts of Teams recordings. To start, simply paste the transcript into the chat box.'
```

---

#### promptPrefix

<OptionTable
  options={[
    [
      'promptPrefix',
      'String (nullable)',
      'A static text prepended to every prompt sent to the model, setting a consistent context for responses.',
      'When using "assistants" as the endpoint, this becomes the OpenAI field `additional_instructions`.',
    ],
  ]}
/>

**Default:** `None`

**Example 1:**

```yaml filename="modelSpecs / list / {spec_item} / preset / promptPrefix"
preset:
  promptPrefix: 'As a financial advisor, ...'
```

**Example 2:**

```yaml filename="modelSpecs / list / {spec_item} / preset / promptPrefix"
preset:
  promptPrefix: |
    Based on the transcript, create coherent meeting minutes for a business meeting. Include the following sections:
    - Date and Attendees
    - Agenda
    - Minutes
    - Action Items

    Focus on what items were discussed and/or resolved. List any open action items.
    The format should be a bulleted list of high level topics in chronological order, and then one or more concise sentences explaining the details.
    Each high level topic should have at least two sub topics listed, but add as many as necessary to support the high level topic. 

    - Do not start items with the same opening words.

    Take a deep breath and be sure to think step by step.
```

---

#### resendFiles

<OptionTable
  options={[
    [
      'resendFiles',
      'Boolean',
      'Indicates whether files should be resent in scenarios where persistent sessions are not maintained.',
      '',
    ],
  ]}
/>

**Default:** `true`

Google model settings now expose this control in the shared schema, so administrators can explicitly choose whether files are resent on later turns for Google and Vertex AI model specs.

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / resendFiles"
preset:
  resendFiles: true
```

---

#### imageDetail

**Accepted Values:**

- low
- auto
- high

<OptionTable
  options={[
    [
      'imageDetail',
      'Enum (eImageDetailSchema)',
      'Specifies the level of detail required in image analysis tasks, applicable to models with vision capabilities (OpenAI spec).',
      '',
    ],
  ]}
/>

**Default:** `"auto"`

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / imageDetail"
preset:
  imageDetail: 'high'
```

---

#### maxContextTokens

<OptionTable
  options={[
    [
      'maxContextTokens',
      'Number',
      'The maximum number of context tokens to provide to the model.',
      'Useful if you want to limit the maximum context for this preset.',
    ],
  ]}
/>

For Google model settings, the Agent Builder accepts values from `10` to `2,000,000` and uses increments of `1,000`.

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / maxContextTokens"
preset:
  maxContextTokens: 4096
```

---

### Agent Options

Note that these options are only applicable when using the `agents` endpoint.

You should exclude any model options and defer to the agent's configuration as defined in the UI.

<Callout type="info" title="Agent Access Filtering (v0.8.0+)">
As of v0.8.0, LibreChat uses an ACL (Access Control List) based permissions system for agents. When model specs are configured to use agents, any agents that the user doesn't have access to will be automatically filtered out, even if they are configured in the model spec. This ensures users only see and can use agents they have proper permissions for.

The server also resolves the effective model spec and authorizes its persistent `agent_id` before loading or running that Agent. A caller cannot use request fields or a preset mismatch to substitute a different Agent after this access check.

For more information about the ACL permissions system, see the [Agents documentation](/docs/features/agents#migration-required-v080-rc3).

</Callout>

---

#### agent_id

<OptionTable options={[['agent_id', 'String', 'Identification of an assistant.', '']]} />

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / agent_id"
preset:
  agent_id: 'agent_someUniqueId'
```

---

### Assistant Options

Note that these options are only applicable when using the `assistants` or `azureAssistants` endpoint.

Similar to [Agents](#agent-options), you should exclude any model options and defer to the assistant's configuration.

---

#### assistant_id

<OptionTable options={[['assistant_id', 'String', 'Identification of an assistant.', '']]} />

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / assistant_id"
preset:
  assistant_id: 'asst_someUniqueId'
```

---

#### instructions

**Note:** this is distinct from [`promptPrefix`](#promptPrefix), as this overrides existing assistant instructions for current runs.

Only use this if you want to override the assistant's core instructions.

Use [`promptPrefix`](#promptPrefix) for `additional_instructions`.

More information:

- https://platform.openai.com/docs/api-reference/models#runs-createrun-instructions
- https://platform.openai.com/docs/api-reference/runs/createRun#runs-createrun-additional_instructions

<OptionTable
  options={[['instructions', 'String', "Overrides the assistant's default instructions.", '']]}
/>

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / instructions"
preset:
  instructions: 'Please handle customer queries regarding order status.'
```

---

#### append_current_datetime

Adds the current date and time to `additional_instructions` for each run. Does not overwrite `promptPrefix`, but adds to it.

<OptionTable
  options={[
    [
      'append_current_datetime',
      'Boolean',
      'Adds the current date and time to `additional_instructions` as defined by `promptPrefix`',
      '',
    ],
  ]}
/>

**Example:**

```yaml filename="modelSpecs / list / {spec_item} / preset / append_current_datetime"
preset:
  append_current_datetime: true
```

---

### Model Options

> **Note:** Each parameter below includes a note on which endpoints support it.  
> **OpenAI / AzureOpenAI / Custom** typically support `temperature`, `presence_penalty`, `frequency_penalty`, `stop`, `top_p`, `max_tokens`.  
> **Google / Anthropic** typically support `topP`, `topK`, `maxOutputTokens`; Google also supports `url_context` on supported Gemini text models.
> **Anthropic / OpenRouter / Bedrock (Anthropic and Nova models)** support `promptCache` and `promptCacheTtl`.
> **Bedrock** supports `region`, `maxTokens`, and a few others.

#### model

> **Supported by:** All endpoints (except `agents`)

<OptionTable
  options={[
    [
      'model',
      'String (nullable)',
      'The model name to use for the preset, matching a configured model under the chosen endpoint.',
      'None',
    ],
  ]}
/>

**Default:** `None`

**Example:**

```yaml
preset:
  model: 'gpt-4-turbo'
```

---

#### temperature

> **Supported by:** `openAI`, `azureOpenAI`, `google` (as `temperature`), `anthropic` (as `temperature`), and custom (OpenAI-like)

<OptionTable
  options={[
    [
      'temperature',
      'Number',
      'Controls how deterministic or “creative” the model responses are.',
      '',
    ],
  ]}
/>

**Example:**

```yaml
preset:
  temperature: 0.7
```

---

#### presence_penalty

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)  
> _Not typically used by Google/Anthropic/Bedrock_

<OptionTable
  options={[
    [
      'presence_penalty',
      'Number',
      'Penalty for repetitive tokens, encouraging exploration of new topics.',
      '',
    ],
  ]}
/>

**Example:**

```yaml
preset:
  presence_penalty: 0.3
```

---

#### frequency_penalty

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)  
> _Not typically used by Google/Anthropic/Bedrock_

<OptionTable
  options={[
    [
      'frequency_penalty',
      'Number',
      'Penalty for repeated tokens, reducing redundancy in responses.',
      '',
    ],
  ]}
/>

**Example:**

```yaml
preset:
  frequency_penalty: 0.5
```

---

#### stop

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)  
> _Not typically used by Google/Anthropic/Bedrock_

<OptionTable
  options={[
    [
      'stop',
      'Array of Strings',
      'Stop tokens for the model, instructing it to end its response if encountered.',
      '',
    ],
  ]}
/>

**Example:**

```yaml
preset:
  stop:
    - 'END'
    - 'STOP'
```

---

#### top_p

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)  
> **Google/Anthropic** often use `topP` (capital “P”) instead of `top_p`.

<OptionTable
  options={[
    [
      'top_p',
      'Number',
      'Nucleus sampling parameter (0-1), controlling the randomness of tokens.',
      '',
    ],
  ]}
/>

**Example:**

```yaml
preset:
  top_p: 0.9
```

---

#### topP

> **Supported by:** `google` & `anthropic`  
> (similar purpose to `top_p`, but named differently in those APIs)

<OptionTable
  options={[['topP', 'Number', 'Nucleus sampling parameter for Google/Anthropic endpoints.', '']]}
/>

**Example:**

```yaml
preset:
  topP: 0.8
```

---

#### topK

> **Supported by:** `google` & `anthropic`  
> (k-sampling limit on the next token distribution)

<OptionTable
  options={[['topK', 'Number', 'Limits the next token selection to the top K tokens.', '']]}
/>

**Example:**

```yaml
preset:
  topK: 40
```

---

#### max_tokens

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)  
> _For Google/Anthropic, use `maxOutputTokens` or `maxTokens` (depending on the endpoint)._

<OptionTable
  options={[['max_tokens', 'Number', 'The maximum number of tokens in the model response.', '']]}
/>

**Example:**

```yaml
preset:
  max_tokens: 4096
```

---

#### maxOutputTokens

> **Supported by:** `google`, `anthropic`  
> _Equivalent to `max_tokens` for these providers._

<OptionTable
  options={[
    [
      'maxOutputTokens',
      'Number',
      'The maximum number of tokens in the response (Google/Anthropic).',
      '',
    ],
  ]}
/>

**Example:**

```yaml
preset:
  maxOutputTokens: 2048
```

---

#### promptCache

> **Supported by:** `anthropic`, OpenRouter custom endpoints, `bedrock` (Anthropic and Nova models)
> (Toggle provider prompt caching)

<OptionTable
  options={[
    ['promptCache', 'Boolean', 'Enables or disables provider prompt caching.', ''],
  ]}
/>

**Default:** `true`

**Example:**

```yaml
preset:
  promptCache: true
```

**Note:** For Bedrock endpoints, prompt caching is automatically enabled for Claude and Nova models. Set `promptCache: false` to explicitly disable it.

---

#### promptCacheTtl

> **Supported by:** `anthropic`, OpenRouter custom endpoints, `bedrock` (Anthropic and Nova models)
> (Sets the prompt-cache lifetime when prompt caching is enabled)

<OptionTable
  options={[
    [
      'promptCacheTtl',
      'Enum',
      'Sets the prompt-cache lifetime. Supported values are `5m` and `1h`.',
      'Provider or SDK default',
    ],
  ]}
/>

**Accepted Values:**

- `5m`
- `1h`

**Example:**

```yaml
preset:
  promptCache: true
  promptCacheTtl: '1h'
```

**Note:** `promptCacheTtl` is ignored when prompt caching is disabled. When omitted, the provider integration uses its default prompt-cache lifetime.

---

#### reasoning_effort

**Accepted Values:**

- `""` (empty string — unset, uses API default)
- `"none"`
- `"minimal"`
- `"low"`
- `"medium"`
- `"high"`
- `"xhigh"` (extra high)
- `"max"` (maximum)

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like), `bedrock` (ZAI, MoonshotAI models)

<OptionTable
  options={[
    [
      'reasoning_effort',
      'String',
      'Controls the reasoning effort level for the model. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning. Supported OpenAI models may expose `xhigh` and `max`; for Bedrock, accepted values are `low`, `medium`, `high`.',
      '',
    ],
  ]}
/>

**Default:** `""` (unset)

**Example:**

```yaml
preset:
  reasoning_effort: 'low'
```

---

#### reasoning_summary

**Accepted Values:**

- `""` (empty string — disables reasoning summaries)
- `"auto"`
- `"concise"`
- `"detailed"`

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)

<OptionTable
  options={[
    ['reasoning_summary', 'String', 'Sets reasoning summary preferences for the model.', ''],
  ]}
/>

**Default:** `""` (disabled)

**Example:**

```yaml
preset:
  reasoning_summary: 'detailed'
```

---

#### reasoning_mode

**Accepted Values:**

- `""` (empty string - unset)
- `"standard"`
- `"pro"`

> **Supported by:** OpenAI Responses API models that expose reasoning mode, including GPT-5.6

<OptionTable
  options={[
    ['reasoning_mode', 'String', 'Sets the OpenAI Responses API reasoning mode.', ''],
  ]}
/>

```yaml
preset:
  reasoning_effort: 'high'
  reasoning_mode: 'pro'
```

---

#### reasoning_context

**Accepted Values:**

- `""` (empty string - unset)
- `"auto"`
- `"current_turn"`
- `"all_turns"`

> **Supported by:** OpenAI Responses API models that expose reasoning context, including GPT-5.6

<OptionTable
  options={[
    [
      'reasoning_context',
      'String',
      'Controls how much conversational context is available to model reasoning.',
      '',
    ],
  ]}
/>

```yaml
preset:
  reasoning_effort: 'high'
  reasoning_context: 'all_turns'
```

For GPT-5.6, LibreChat defaults reasoning requests to the Responses API unless `useResponsesApi: false` is set explicitly.

---

#### useResponsesApi

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)

<OptionTable
  options={[
    ['useResponsesApi', 'Boolean', 'Enables or disables the responses API for the model.', ''],
  ]}
/>

**Default:** `false`

**Example:**

```yaml
preset:
  useResponsesApi: true
```

---

#### verbosity

**Accepted Values:**

- `""` (empty string — unset, uses API default)
- `"low"`
- `"medium"`
- `"high"`

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)

<OptionTable
  options={[['verbosity', 'String', 'Controls the verbosity level of model responses.', '']]}
/>

**Default:** `""` (unset)

**Example:**

```yaml
preset:
  verbosity: 'low'
```

---

#### web_search

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like), `google`, `anthropic`

<OptionTable
  options={[
    ['web_search', 'Boolean', 'Enables or disables web search functionality for the model.', ''],
  ]}
/>

**Default:** `false`

**Note:** For Google endpoints, this parameter appears as `Grounding with Google Search` in the actual panel but controls `web_search` in the implementation.

**Example:**

```yaml
preset:
  web_search: true
```

---

#### url_context

> **Supported by:** `google` on supported Gemini text models, including Gemini 2.5+ and Gemini 3.x

<OptionTable
  options={[
    [
      'url_context',
      'Boolean',
      'Enables Google URL Context so the model can read URLs included in the user message. YouTube links are converted to native video-understanding inputs when possible.',
      '',
    ],
  ]}
/>

**Default:** `false`

**Example:**

```yaml
preset:
  url_context: true
```

---

#### disableStreaming

> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)

<OptionTable
  options={[['disableStreaming', 'Boolean', 'Disables streaming responses from the model.', '']]}
/>

**Default:** `false`

**Example:**

```yaml
preset:
  disableStreaming: true
```

---

#### thinkingBudget

> **Supported by:** `google`, `anthropic`, `bedrock` (Anthropic models)

<OptionTable
  options={[
    [
      'thinkingBudget',
      'Number or String',
      'Controls the number of thinking tokens the model can use for internal reasoning. Larger budgets can improve response quality for complex problems.',
      '',
    ],
  ]}
/>

**Default:** `"Auto (-1)"` (Google), `2000` (Anthropic, Bedrock (Anthropic models))

For Gemini 2.5 models, the Google setting is model-aware: Pro accepts `128`-`32768`, Flash accepts `0`-`24576`, and Flash-Lite accepts `512`-`24576`. `-1` remains the automatic setting. Gemini 3+ models use [`thinkingLevel`](#thinkinglevel) instead of a numeric budget.

**Example:**

```yaml
preset:
  thinkingBudget: '2000'
```

---

#### thinkingLevel

> **Supported by:** `google` (Gemini 3+ models)

<OptionTable
  options={[
    [
      'thinkingLevel',
      'String',
      'Controls the thinking effort level for Gemini 3+ models. Gemini 2.5 models use `thinkingBudget` instead.',
      '',
    ],
  ]}
/>

**Accepted Values:**

- `""` (unset/auto)
- `"minimal"`
- `"low"`
- `"medium"`
- `"high"`

**Default:** `""` (unset — model decides)

**Example:**

```yaml
preset:
  thinkingLevel: 'medium'
```

---

#### effort

> **Supported by:** `anthropic`, `bedrock` (Anthropic models)

<OptionTable
  options={[
    [
      'effort',
      'String',
      'Controls the Adaptive Thinking effort level for supported Anthropic models (e.g., Claude Opus 4.6+ and Claude Fable/Mythos-class models). Higher effort levels allocate more thinking tokens for complex problems.',
      '',
    ],
  ]}
/>

**Options:** `""` (unset/auto), `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`

**Default:** `""` (unset — model decides)

**Example:**

```yaml
preset:
  effort: 'high'
```

---

#### thinkingDisplay

> **Supported by:** `anthropic`, `bedrock` (Anthropic models)

<OptionTable
  options={[
    [
      'thinkingDisplay',
      'String',
      'Controls whether reasoning content is returned in model responses. Claude Opus 4.7+ and Claude Fable/Mythos-class models omit thinking content by default; this setting lets you opt in to reasoning summaries or explicitly suppress them.',
      '',
    ],
  ]}
/>

**Options:** `"auto"` (default), `"summarized"`, `"omitted"`

- `"auto"` — LibreChat decides: opts in to `"summarized"` for models that omit thinking by default (Opus 4.7+ and Fable/Mythos-class), leaves the field off for older models
- `"summarized"` — always request a post-hoc summary of the reasoning
- `"omitted"` — always suppress reasoning content (slightly lower latency)

**Default:** `"auto"`

**Example:**

```yaml
preset:
  thinkingDisplay: 'summarized'
```

---

#### thinking

> **Supported by:** `google`, `anthropic`, `bedrock` (Anthropic models)

<OptionTable
  options={[
    [
      'thinking',
      'Boolean',
      'Indicates whether the model should spend time thinking before generating a response.',
      '',
    ],
  ]}
/>

**Default:** `true`

**Example:**

```yaml
preset:
  thinking: true
```

---

#### region

> **Supported by:** `bedrock`  
> (Used to specify an AWS region for Amazon Bedrock)

<OptionTable options={[['region', 'String', 'AWS region for Amazon Bedrock endpoints.', '']]} />

**Example:**

```yaml
preset:
  region: 'us-east-1'
```

---

#### maxTokens

> **Supported by:** `bedrock`  
> (Used in place of `max_tokens`)

<OptionTable
  options={[['maxTokens', 'Number', 'Maximum output tokens for Amazon Bedrock endpoints.', '']]}
/>

**Example:**

```yaml
preset:
  maxTokens: 1024
```