# First-time setup

Use this after CrossWatch (CW) is running and the UI loads.

If you still need to install it, start here: [Docker setup](https://wiki.crosswatch.app/getting-started/docker-setup).

Need a platform-specific wrapper instead? See [Install scripts](https://wiki.crosswatch.app/related-information/community/install-scripts) for community-maintained options.

{% hint style="success" %}
CW can do a lot. You do **not** need to configure everything.

For most users, the **defaults are already correct**. Your first goal is a single clean run.

Typical first setup:

* Connect one **media server** and one **tracker**
* Add the optional Metadata provider (**TMDb**)
* Create one **pair** (one-way and one feature)
  {% endhint %}

{% hint style="warning" %}
**Save often.** Most changes do nothing until you click the **red floating Save button**.\
Click **Save** after every step below.\
\
Before you build pairs, make sure your library size is a good fit for CrossWatch.

If your watchlists, history, or ratings are far beyond the recommended ranges, stop here and read [Limitations](https://wiki.crosswatch.app/getting-started/limitations).
{% endhint %}

### Choose your path

* **Syncing** aligns watchlists, history, and ratings.
* **Scrobbling** pushes plays while you watch.

If you’re unsure, start here: [What do you need?](https://wiki.crosswatch.app/getting-started/first-time-setup/what-do-you-need)

### Recommended order

1. Providers (authentication)
2. Providers (metadata / TMDb)
3. Sync pairs (syncing)
4. Scrobbler (Watcher, optional)

{% stepper %}
{% step %}

### 1) Connect authentication providers

Open **Settings → Providers**.

Start with **one media server** and **one tracker**. Validate one clean run. Then add more providers.

1. Click **Connect** / **Sign In** for the provider.
2. Approve access in the new tab.
3. Return to CW.
4. Verify URLs and IDs. Use **Auto-Fetch** when available.
5. Click the **red Save button**.

Related:

* [Authentication](https://wiki.crosswatch.app/crosswatch/providers/authentication)
* [Providers](https://wiki.crosswatch.app/crosswatch/providers)
  {% endstep %}

{% step %}

### 2) Configure metadata (TMDb)

Open **Settings → Providers** and configure **TMDb**.

Set up TMDb before your first real sync. It improves matching and reduces wrong links.

1. Enable **TMDb**.
2. Create a TMDb API key.
3. Paste the key into CW.
4. Click the **red Save button**.

Related: [Meta: TMDb](https://wiki.crosswatch.app/crosswatch/providers/metadata/meta-tmdb)
{% endstep %}

{% step %}

### 3) Create your first pair (syncing)

If you want syncing, open **Settings → Sync pairs**.

{% hint style="info" %}
Do not overthink this screen. The defaults are good for most users.

Most setups only require enabling a feature. You can usually leave **Global** and **Provider** settings unchanged.
{% endhint %}

Use the safest first run:

* **Mode**: one-way
* **Features**: enable **one** (Watchlist, History, Ratings, or Progress)
* **Dry run**: enabled

{% hint style="info" %}
Progress only shows up for **Plex/Emby/Jellyfin** pairs.
{% endhint %}

1. Pick **Source** (left) and **Target** (right).
2. Enable one feature tab.
3. Keep defaults in **Global** and **Provider** settings.
4. Leave mass deletes off.
5. Click the **red Save button**.

Related:

* [Syncing](https://wiki.crosswatch.app/getting-started/first-time-setup/what-do-you-need/syncing)
* [Configure Pairs](https://wiki.crosswatch.app/crosswatch/configure-pairs)
  {% endstep %}

{% step %}

### 4) Run once, then iterate

Run a sync. Review what it planned. Fix matching before you enable more features.

Use these tools when something looks off:

* [Analyzer](https://wiki.crosswatch.app/crosswatch/tools/analyzer) for missing peers and mismatches
* [Editor](https://wiki.crosswatch.app/crosswatch/tools/editor) for overrides, blocks, and cleanup

When the pair is stable:

* Disable **Dry run**.
* Add one more feature.
* Add the next pair.
  {% endstep %}

{% step %}

### 5) Optional: enable scrobbling (Watcher)

Open **Settings → Scrobbler**.

Use **Watcher** by default. Legacy webhooks are deprecated.

{% hint style="info" %}
Same idea as Pairs. Defaults are good. Pick your Provider and Sink, then enable Watcher.
{% endhint %}

1. Connect your media server and at least one tracker target.
2. Open **Watcher**.
3. Set **Provider** (source) and **Sink** (targets).
4. Enable Watcher.
5. Click the **red Save button**.

{% hint style="warning" %}
Use Watcher unless you have a specific reason not to.
{% endhint %}

{% hint style="info" %}
You cannot enable **Watcher** and **Webhook** at the same time. Pick one mode.
{% endhint %}

Related:

* [Webhook or Watcher](https://wiki.crosswatch.app/getting-started/first-time-setup/what-do-you-need/webhook-or-watcher)
* [Watcher](https://wiki.crosswatch.app/crosswatch/scrobble/watcher)
  {% endstep %}

{% step %}

### 6) Optional: add scheduling

If you want automatic periodic runs, open **Settings → Scheduling**.

Start with a daily cadence. Avoid overlaps.

Click the **red Save button**.

Related: [Scheduling](https://wiki.crosswatch.app/crosswatch/scheduling)
{% endstep %}
{% endstepper %}

### Quick checklist

* Providers are connected.
* Providers show up in **Sync pairs**.
* TMDb is configured and saved.
* First pair is one-way and dry run.
* Scrobbling is configured only if you need it.
* You clicked the red **Save** button after each step.

Related: [Settings](https://wiki.crosswatch.app/crosswatch/navigation/settings)

### Summary

Connect one media server + one tracker.

Add TMDb before your first real run.

Create one safe pair (one-way + one feature + dry run), then iterate.

### Next steps

* Lock in safe pair defaults: [Best practices](https://wiki.crosswatch.app/getting-started/best-practices)
* Check whether your library size is a good fit: [Limitations](https://wiki.crosswatch.app/getting-started/limitations)
* Deep-dive pair controls (guards, features, Blackbox): [Configure Pairs](https://wiki.crosswatch.app/crosswatch/configure-pairs)
* Enable real-time plays once syncing is stable: [Watcher](https://wiki.crosswatch.app/crosswatch/scrobble/watcher)
* Debug missing peers and ID issues: [Analyzer](https://wiki.crosswatch.app/crosswatch/tools/analyzer)


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/getting-started/first-time-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.