UITarsModelVersion and Provider Selection Relationship in UI-TARS Desktop

The UITarsModelVersion enum value is determined by mapping the user-selected VLMProviderV2 provider through the getModelVersion utility function, with a fallback to remote cloud configuration when no local provider is specified.

In the bytedance/UI-TARS-desktop repository, the relationship between model versions and Vision-Language Model (VLM) providers forms the core configuration logic that determines how the SDK processes screenshots and generates UI automation actions. This mapping ensures that the correct token limits, image preprocessing parameters, and system prompts are applied based on whether you are running UI-TARS 1.0, UI-TARS 1.5, or one of the Doubao-hosted variants.

Provider-to-Version Enum Mapping

The relationship begins with two tightly coupled enums defined in apps/ui-tars/src/main/store/types.ts. The VLMProviderV2 enum represents the user's provider selection, while UITarsModelVersion represents the internal model capabilities that the SDK consumes.

The mapping follows this pattern:

• VLMProviderV2.ui_tars_1_0 → UITarsModelVersion.V1_0
• VLMProviderV2.ui_tars_1_5 → UITarsModelVersion.V1_5
• VLMProviderV2.doubao_1_5 → UITarsModelVersion.DOUBAO_1_5_15B
• VLMProviderV2.doubao_1_5_vl → UITarsModelVersion.DOUBAO_1_5_20B

These definitions reside in packages/ui-tars/shared/src/constants/vlm.ts and are imported throughout the application to maintain type safety across the main process and renderer.

Local Resolution with getModelVersion

When the application initializes a GUI agent session, it calls getModelVersion in apps/ui-tars/src/main/utils/agent.ts to translate the user's provider preference into a model version constant.

export const getModelVersion = (
  provider: VLMProviderV2 | undefined,
): UITarsModelVersion => {
  switch (provider) {
    case VLMProviderV2.ui_tars_1_5:
      return UITarsModelVersion.V1_5;
    case VLMProviderV2.ui_tars_1_0:
      return UITarsModelVersion.V1_0;
    case VLMProviderV2.doubao_1_5:
      return UITarsModelVersion.DOUBAO_1_5_15B;
    case VLMProviderV2.doubao_1_5_vl:
      return UITarsModelVersion.DOUBAO_1_5_20B;
    default:
      return UITarsModelVersion.V1_0;
  }
};

This switch statement acts as the single source of truth for provider-to-version translation. If the provider parameter is undefined, the function defaults to V1_0 to maintain backward compatibility with older UI-TARS deployments.

Remote Provider Fallback Mechanism

If no local provider is configured, the application queries the cloud proxy to determine the appropriate model. The getRemoteVLMProvider static method in apps/ui-tars/src/main/remote/proxyClient.ts handles this by mapping server-returned string identifiers to the same UITarsModelVersion enum.

public static async getRemoteVLMProvider(): Promise<UITarsModelVersion> {
  const res = await this.instance.getRemoteVLMProvider();
  let modelVer = UITarsModelVersion.DOUBAO_1_5_20B;
  switch (res) {
    case 'UI-TARS-1.5':
      modelVer = UITarsModelVersion.V1_5;
      break;
    case 'UI-TARS-1.0':
      modelVer = UITarsModelVersion.V1_0;
      break;
    case 'Doubao-1.5-UI-TARS':
      modelVer = UITarsModelVersion.DOUBAO_1_5_15B;
      break;
    case 'Doubao-1.5-thinking-vision-pro':
      modelVer = UITarsModelVersion.DOUBAO_1_5_20B;
      break;
    default:
      modelVer = UITarsModelVersion.DOUBAO_1_5_20B;
  }
  return modelVer;
}

This ensures that enterprise deployments using the VolcEngine Ark proxy can dynamically assign model versions without requiring local configuration changes.

Runtime Behavior Based on Model Version

Once resolved, the UITarsModelVersion value flows into the SDK's Model.ts and vlm.ts modules to configure runtime parameters. The version affects several critical execution paths:

• Token Limits – V1.5 receives a 65,535 token limit, while V1.0 falls back to 1,000 tokens according to logic in packages/ui-tars/sdk/src/Model.ts line 110.
• Image Preprocessing – Maximum pixel constraints vary by version (MAX_PIXELS_V1_0, MAX_PIXELS_V1_5, MAX_PIXELS_DOUBAO) to optimize bandwidth and inference costs.
• System Prompt Selection – The getSpByModelVersion function selects specialized system prompts optimized for each model's training data and reasoning capabilities.

Complete Configuration Flow

The relationship between provider selection and model version follows this execution path:

1. User selection is stored in settings.vlmProvider via the settings store.
2. Agent initialization calls getModelVersion(settings.vlmProvider) from apps/ui-tars/src/main/utils/agent.ts.
3. Fallback handling triggers ProxyClient.getRemoteVLMProvider() if the local provider is undefined.
4. SDK configuration passes the resolved UITarsModelVersion to runAgent and GUIAgent constructors.
5. Request shaping applies version-specific token limits and image preprocessing before calling the VLM API.

Practical Implementation Examples

Resolving Version from Local Settings

import { VLMProviderV2 } from '@ui-tars/shared/constants';
import { getModelVersion } from './utils/agent';

const userProvider: VLMProviderV2 = VLMProviderV2.doubao_1_5_vl;
const modelVersion = getModelVersion(userProvider);
// Returns: UITarsModelVersion.DOUBAO_1_5_20B

Handling Remote Configuration

import { ProxyClient } from './remote/proxyClient';

async function initializeAgent() {
  const version = await ProxyClient.getRemoteVLMProvider();
  return version; // UITarsModelVersion based on cloud config
}

Configuring Model Parameters

import { getSpByModelVersion } from './utils/agent';
import { UITarsModelVersion } from '@ui-tars/shared/constants';

const systemPrompt = getSpByModelVersion(
  UITarsModelVersion.V1_5,
  'en',
  'computer'
);

Summary

• Provider enums map directly to model versions through the getModelVersion switch statement in apps/ui-tars/src/main/utils/agent.ts.
• Cloud deployments use remote resolution via ProxyClient.getRemoteVLMProvider() to translate server strings into UITarsModelVersion values.
• Version determines runtime limits including token budgets (65,535 vs 1,000) and maximum image pixels (MAX_PIXELS_V1_5, MAX_PIXELS_DOUBAO).
• Default fallback is V1_0 for undefined local providers and DOUBAO_1_5_20B for unrecognized remote responses.
• System prompt selection uses getSpByModelVersion to load version-optimized instructions for the VLM.

Frequently Asked Questions

What happens if I select a provider but the model version is not detected?

The getModelVersion function defaults to UITarsModelVersion.V1_0 when the provider parameter is undefined or unrecognized, ensuring the application remains functional with conservative token limits. This fallback is hardcoded in the switch statement's default case within apps/ui-tars/src/main/utils/agent.ts.

Can I use the Doubao provider with the open-source UI-TARS model weights?

No, the VLMProviderV2.doubao_1_5 and doubao_1_5_vl options are specifically configured for VolcEngine Ark API endpoints and map to DOUBAO_1_5_15B and DOUBAO_1_5_20B versions respectively. To use open-source UI-TARS weights locally or via Hugging Face, select ui_tars_1_0 or ui_tars_1_5 which map to the V1_0 and V1_5 model versions.

How does the model version affect screenshot preprocessing?

The version determines the MAX_PIXELS constant applied during image encoding in vlm.ts. UI-TARS 1.5 allows higher resolution inputs than 1.0, while the Doubao variants use distinct pixel limits optimized for the VolcEngine inference infrastructure. This affects both screenshot compression quality and API bandwidth consumption.

Where is the model version stored during an agent session?

The resolved UITarsModelVersion is passed directly to the SDK's Model class constructor and stored in the agent runtime state. It is not persisted to disk; instead, it is resolved fresh from settings.vlmProvider (or the remote proxy) each time runAgent initializes a new GUI automation session.

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