> 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/getting-started/first-time-setup.md).
# First-time setup
Connect providers and add TMDb metadata
Use this after CrossWatch (CW) is running and the UI loads.
If you still need to install it, start here: [Docker setup](/getting-started/installation.md).
Need a platform-specific wrapper instead? See [Install scripts](/related-information/community/install-scripts.md) 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 or media client** and one **tracker**
* Add the Metadata provider (**TMDb**)
* Create one **pair** (one-way and one feature)
{% endhint %}
{% hint style="warning" %}
Save each connection with **Save changes** and each sync pair with **Save**. Other settings show their own save controls; save before closing the dialog.
If your watchlists, history, or ratings are far beyond the recommended ranges, stop here and read [Limitations](/getting-started/limitations.md).
{% endhint %}
If you only need real-time playback, jump to [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md).
### Recommended order
1. Connections
2. Metadata / ID Mapping (TMDb)
3. Synchronization (optional)
4. Scrobbler (optional)
{% stepper %}
{% step %}
### 1) Connect providers
Open **Settings → Connections**.
Start with **one media server or media client** and **one tracker**. Validate one clean run. Then add more providers.
Good first trackers are **Trakt**, **SIMKL**, **MDBList**, or **PublicMetaDB**.
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. Save the settings before continuing.
Related:
* [Connections](/crosswatch/settings/connections.md)
{% endstep %}
{% step %}
### 2) Configure metadata (TMDb)
Open **Settings → Connections**.
Set up TMDb before your first real sync. It improves matching and reduces wrong links.
TMDb is strongly recommended.
CrossWatch uses TMDb for many features, including posters, backdrops, richer metadata, and more reliable matching.
1. Click **Add metadata** and select **TMDb Metadata**.
2. Create a TMDb API key.
3. Paste the key into CW.
4. Save the settings before continuing.
Related: [Meta: TMDb](/crosswatch/settings/connections/metadata/tmdb-metadata.md)
{% endstep %}
{% step %}
### 3) Create your first pair
If you want syncing, open **Synchronization**.
{% hint style="info" %}
Do not overthink this screen. The defaults are good for most users.
You can 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 is available when the source can read resume positions and the target can write them. See the [pair synchronization matrix](/getting-started/support-matrix/pair-synchronization.md) for supported providers.
{% endhint %}
1. Pick **Source** (left) and **Target** (right).
2. Enable one feature tab.
3. Keep defaults in **Global** and **Provider** settings.
4. Save the settings before continuing.
Related:
* [Configure Pairs](/crosswatch/settings/configure-pairs.md)
{% 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](/crosswatch/main-dashboard/tools/analyzer.md) for missing peers and mismatches
* [Editor](/crosswatch/main-dashboard/navigation/editor.md) 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. Use Webhooks when server-delivered events suit your setup.
{% hint style="info" %}
Create one route, then start Watcher or enable Autostart.
{% endhint %}
1. Connect your media server and at least one tracker target.
2. Open **Settings → Scrobbler**.
3. Select **Add watcher**.
4. Select the source and destination instances.
5. Select **Save changes**.
6. Start Watcher or enable **Autostart**.
{% hint style="info" %}
Most setups should use only one mode, preferable Watcher.
You can run **Watcher** and **Webhooks** together when they own separate source and destination pairs.
{% endhint %}
Related:
* [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md)
* [Watcher](/crosswatch/settings/scrobbler/watcher.md)
{% endstep %}
{% step %}
### 6) Optional: add scheduling
If you want automatic periodic runs, open **Settings → Scheduling**.
Start with a daily cadence. Avoid overlaps.
Save the settings before continuing.
Related: [Scheduling](/crosswatch/settings/scheduling.md)
{% 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](/crosswatch/settings.md)
### Summary
Connect one media server and one tracker.
Add TMDb before your first real run.
### Next steps
* Lock in safe pair defaults: [Best practices](/getting-started/best-practices.md)
* Check whether your library size is a good fit: [Limitations](/getting-started/limitations.md)
* Deep-dive pair controls (guards, features, Blackbox): [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* Enable real-time plays once syncing is stable: [Watcher](/crosswatch/settings/scrobbler/watcher.md)
* Debug missing peers and ID issues: [Analyzer](/crosswatch/main-dashboard/tools/analyzer.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/getting-started/first-time-setup.md?ask=&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.