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.

Need a platform-specific wrapper instead? See Install scripts for community-maintained options.

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)

Save often. Most changes do nothing until you click the red floating Save button. Click Save after every step below.

If your watchlists, history, or ratings are far beyond the recommended ranges, stop here and read Limitations.

Title

Connect providers first

Target

Connections

Title

Configure sync pairs

Target

Configure Pairs

Title

Enable real-time playback

Target

Watcher

Title

Check exact provider support

Target

Support matrix

If you only need real-time playback, jump to Webhook or Watcher.

Recommended order

1. Connections
2. Metadata / ID Mapping (TMDb)
3. Synchronization (optional)
4. Scrobbler (optional)

1

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. Click the red Save button.

Related:

• Connections

2

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. Enable TMDb.
2. Create a TMDb API key.
3. Paste the key into CW.
4. Click the red Save button.

Related: Meta: TMDb

3

3) Create your first pair

If you want syncing, open Synchronization.

Do not overthink this screen. The defaults are good for most users.

You can leave Global and Provider settings unchanged.

Use the safest first run:

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

Progress shows up for Plex, Emby, Jellyfin, Nuvio, and PublicMetaDB pairs.

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

Related:

• Configure Pairs

4

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 for missing peers and mismatches
• Editor for overrides, blocks, and cleanup

When the pair is stable:

• Disable Dry run.
• Add one more feature.
• Add the next pair.

5

5) Optional: enable scrobbling (Watcher)

Open Settings → Scrobbler.

Use Watcher by default. Use Webhooks when server-delivered events suit your setup.

Create one route, then start Watcher or enable Autostart.

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 profiles.
5. Select Save changes.
6. Start Watcher or enable Autostart.

Most setups should use only one mode, preferable Watcher.

You can run Watcher and Webhooks together when they own separate source and destination pairs.

Related:

• Webhook or Watcher
• Watcher

6

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

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

Summary

Connect one media server and one tracker.

Add TMDb before your first real run.

Next steps

• Lock in safe pair defaults: Best practices
• Check whether your library size is a good fit: Limitations
• Deep-dive pair controls (guards, features, Blackbox): Configure Pairs
• Enable real-time plays once syncing is stable: Watcher
• Debug missing peers and ID issues: Analyzer