# UITarsModelVersion and Provider Selection Relationship in UI-TARS Desktop

> Understand the UITarsModelVersion and provider selection relationship in UI-TARS Desktop. Learn how VLMProviderV2 maps to model versions with fallback options.

- Repository: [Bytedance Inc./UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop)
- Tags: deep-dive
- Published: 2026-05-10

---

**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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/utils/agent.ts) to translate the user's provider preference into a model version constant.

```typescript
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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/remote/proxyClient.ts) handles this by mapping server-returned string identifiers to the same `UITarsModelVersion` enum.

```typescript
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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/Model.ts) and [`vlm.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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

```typescript
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

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

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

```

### Configuring Model Parameters

```typescript
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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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.