WebAI2API/docs/en/config/instances.md

::: info This English version is translated by Gemini 3 Flash. :::

Instance Configuration

Instance and Worker are the core configuration concepts of WebAI2API.

Concepts

Instance (Browser Instance)

An Instance represents an independent browser process with:

• Dedicated user data directory.
• Independent Cookies and login sessions.
• Optional exclusive proxy configuration.

Worker

A Worker is a single tab within an Instance responsible for interacting with a specific platform. Multiple Workers under the same Instance:

• Share browser data and login states.
• Share proxy configuration.
• Can be of different adapter types.

Configuration Structure

backend:
  pool:
    instances:
      - name: "browser_default"    # Instance ID
        userDataMark: "01"         # Data directory identifier (Optional)
        proxy:                      # Instance-level proxy (Optional)
          enable: true
          type: socks5
          host: 127.0.0.1
          port: 1080
        workers:                    # List of Workers
          - name: "worker1"
            type: lmarena
          - name: "worker2"
            type: zai_is

Instance Settings

Setting	Type	Required	Description
name	string	✅	Unique identifier for the instance, used in logs and Cookie retrieval.
userDataMark	string	❌	Data directory identifier. Leave empty to use the default directory.
proxy	object	❌	Instance-level proxy configuration. See Proxy Settings.
workers	array	✅	List of Worker configurations.

Data Directory

• Default Location: data/camoufoxUserData
• With userDataMark: data/camoufoxUserData_{mark}

Worker Settings

Setting	Type	Required	Description
name	string	✅	Unique identifier for the Worker (must be globally unique).
type	string	✅	Adapter type.
mergeTypes	array	❌	List of adapter types for aggregation mode (required if type=merge).
mergeMonitor	string	❌	Backend to monitor while idle (Optional).

Adapter Types

Type	Description
lmarena	LMArena Image Generation
lmarena_text	LMArena Text Generation
gemini_biz	Gemini Business Image Generation
gemini_biz_text	Gemini Business Text Generation
gemini	Google Gemini
zai_is	zAI Image Generation
nanobananafree_ai	Nano Banana Free
merge	Aggregation Mode (Multiple backends in a single tab)

Model Filter

Each adapter can be configured with its own model allowlist/blocklist to control the available models for that specific adapter.

Configuration

The Model Filter is configured under backend.adapter.<AdapterID>:

backend:
  adapter:
    lmarena:
      returnUrl: false
      modelFilter:
        mode: whitelist                        # whitelist or blacklist
        list:                                  # List of models to enable or disable
          - gemini-3-pro-image-preview
          - gemini-3-pro-image-preview-2k
          - gemini-2.5-flash-image-preview

Settings

Item	Type	Required	Description
mode	string	✅	Filter mode: whitelist or blacklist.
list	array	✅	List of Model IDs.

Filter Modes

• whitelist: Only models specified in the list are allowed; others will be filtered out.
• blacklist: Models specified in the list are disabled; others remain usable.

Recommendations

::: tip Use WebUI for Configuration We recommend using the Adapter Settings interface in the WebUI to configure model filters; visual operation is more convenient. :::

::: warning Notes

• Model IDs must exactly match the IDs actually supported by the adapter.
• In whitelist mode, if the list is empty or there are no matching models, the adapter will be unusable.
• Model filter configurations for each adapter are independent. :::

Aggregation Mode (Merge)

Aggregation mode allows a single tab to support multiple backends, enabling failover:

workers:
  - name: "merged_worker"
    type: merge
    mergeTypes: [gemini_biz, lmarena, zai_is]
    mergeMonitor: gemini_biz  # Backend to monitor while idle

::: tip Advantages of Aggregation Mode

• Saves browser resources.
• Automatic failover.
• Unified login state. :::

Configuration Examples

Single Instance, Single Worker

instances:
  - name: "default"
    workers:
      - name: "worker1"
        type: lmarena

Multi-Instance Isolation

instances:
  # Instance 1: US Proxy
  - name: "browser_us"
    userDataMark: "us"
    proxy:
      enable: true
      type: socks5
      host: us-proxy.example.com
      port: 1080
    workers:
      - name: "us_worker"
        type: lmarena

  # Instance 2: Japan Proxy
  - name: "browser_jp"
    userDataMark: "jp"
    proxy:
      enable: true
      type: socks5
      host: jp-proxy.example.com
      port: 1080
    workers:
      - name: "jp_worker"
        type: lmarena

Aggregation Mode Example

instances:
  - name: "browser_merged"
    workers:
      - name: "all_in_one"
        type: merge
        mergeTypes: [gemini_biz, lmarena, zai_is]
        mergeMonitor: gemini_biz