> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/connections/instances.md).

# Instances

Connect multiple accounts or servers for the same provider.

Instances let you use multiple accounts or servers for one provider.

{% hint style="info" %}
Start with the built-in **default** instance.

Add another instance only when you need another account or server.
{% endhint %}

{% tabs %}
{% tab title="End users" %}

### For most users

Use the **default** instance for each provider.

Set up a provider in **Settings → Connections**.

Choose the instance on each sync pair or Watcher route.

You do not need instance IDs or configuration files.

### When to add an instance

Add an instance when one provider needs separate connections.

Common examples:

* A Plex server at home and another remotely.
* A Trakt account for you and another for a partner.
* Jellyfin servers for separate libraries or households.

### Set up instances in the UI

#### 1. Add the connection

Each instance stores its connection details in **Settings → Connections**.

Select **Instance** to create another connection.

Set its credentials, server URL, user, and provider options.

#### 2. Select instances for sync pairs

Each side of a pair can use its own instance.

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FJMCOvvvo2nnxNwequFSB%2Fimage.png?alt=media&amp;token=fa8a2d4e-9932-4196-b284-0dfa2fce7618" alt=""><figcaption></figcaption></figure>

#### 3. Select instances for Watcher routes

Choose an instance for both the provider and the sink.

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FvFO985hLIKnSim4mPQKP%2Fimage.png?alt=media&amp;token=94519325-575f-46d4-b537-adc449c0b64a" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Instances are independent.

Set each instance's required token, URL, and provider options.
{% endhint %}

{% hint style="warning" %}
Pairs and Watcher routes can reference instances directly.

Before deleting an instance, update each pair or route using it.

Otherwise runs can fail or use the wrong account or server.
{% endhint %}

An instance assigned to two Profiles stays admin-only. See [Profiles](/crosswatch/settings/connections/profiles.md).
{% endtab %}

{% tab title="Power users" %}
This section covers instance IDs, `config.json`, and API fields.

#### Instance IDs

* `default` is reserved.
* Extra instances use `PROVIDER-P##`.
* Examples: `PLEX-P01`, `TRAKT-P01`, `SIMKL-P02`.

The **Instance** button always creates the next free ID.

If `PLEX-P01` already exists, the next instance is `PLEX-P02`.

#### Config and API field names

Use these fields when you edit `config.json` or call the API.

Each provider can define extra instances in an `instances` map.

```json
{
  "plex": {
    "account_token": "...",
    "server_url": "http://plex.local:32400",
    "instances": {
      "PLEX-P01": {
        "account_token": "...",
        "server_url": "https://remote-plex.example"
      }
    }
  }
}
```

Pairs use:

* `source_instance`
* `target_instance`

Both default to `default`.

```json
{
  "pairs": [
    {
      "enabled": true,
      "source": "PLEX",
      "source_instance": "PLEX-P01",
      "target": "TRAKT",
      "target_instance": "TRAKT-P01",
      "mode": "one-way",
      "features": { "watchlist": true, "ratings": false, "history": true, "playlists": false }
    }
  ]
}
```

Watcher routes use `provider_instance` and `sink_instance`.

Each route is:

`provider(instance) → sink(instance)`

```json
{
  "scrobble": {
    "watch": {
      "routes": [
        {
          "id": "R1",
          "enabled": true,
          "provider": "plex",
          "provider_instance": "default",
          "sink": "trakt",
          "sink_instance": "TRAKT-P01",
          "filters": {}
        }
      ]
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Related topics

* Connect providers: [Connections](/crosswatch/settings/connections.md)
* Configure sync pairs: [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* Configure real-time scrobbling: [Watcher](/crosswatch/settings/scrobbler/watcher.md)
* Scope media-server libraries per instance: [Library Whitelisting](/crosswatch/settings/connections/library-whitelisting.md)
* Delegate dedicated provider instances to users: [Managed users](/crosswatch/settings/connections/managed-users.md)
* Group instances and resources into views: [Profiles](/crosswatch/settings/connections/profiles.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/instances.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
