First-time setup
Connect providers, add TMDb metadata, create your first pair, then (optionally) enable Watcher for real-time scrobbling.
Use this after CrossWatch (CW) is running and the UI loads.
If you still need to install it, start here: Docker setup.
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)
Save often. Most changes do nothing until you click the red floating Save button. Click Save after every step below.
First-time setup: avoid Profiles.
Use the default profile for each provider.
Add profiles only after one clean run.
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?
Recommended order
Providers (authentication)
Providers (metadata / TMDb)
Sync pairs (syncing)
Scrobbler (Watcher, optional)
1) Connect authentication providers
Open Settings → Providers.
Start with one media server and one tracker. Validate one clean run. Then add more providers.
Click Connect / Sign In for the provider.
Approve access in the new tab.
Return to CW.
Verify URLs and IDs. Use Auto-Fetch when available.
Click the red Save button.
Related:
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.
Enable TMDb.
Create a TMDb API key.
Paste the key into CW.
Click the red Save button.
Related: Meta: TMDb
3) Create your first pair (syncing)
If you want syncing, open Settings → Sync pairs.
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.
Use the safest first run:
Mode: one-way
Features: enable one (Watchlist, History, Ratings, or Progress)
Dry run: enabled
Progress only shows up for Plex/Emby/Jellyfin pairs.
Pick Source (left) and Target (right).
Enable one feature tab.
Keep defaults in Global and Provider settings.
Leave mass deletes off.
Click the red Save button.
Related:
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:
When the pair is stable:
Disable Dry run.
Add one more feature.
Add the next pair.
5) Optional: enable scrobbling (Watcher)
Open Settings → Scrobbler.
Use Watcher by default. Legacy webhooks are deprecated.
Same idea as Pairs. Defaults are good. Pick your Provider and Sink, then enable Watcher.
Connect your media server and at least one tracker target.
Open Watcher.
Set Provider (source) and Sink (targets).
Enable Watcher.
Click the red Save button.
Use Watcher unless you have a specific reason not to.
You cannot enable Watcher and Webhook at the same time. Pick one mode.
Related:
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 + 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
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
Last updated
Was this helpful?