Operations and limits

Security, storage, runtime behavior, limitations, and repository source paths.

This section covers security behavior, storage layout, runtime notes, and the main repository areas behind each system.

Use this page when you need exact paths, security behavior, or implementation map pointers.

At a glance

Covers

• secret storage and config safety
• state and backup paths
• runtime logging and telemetry

Also includes

• key product limits
• source-map pointers into the repo
• related docs for deeper details

Jump to related docs

Title

Safe defaults and operating guidance

Open

Best practices

Title

Size and provider fit guidance

Open

Limitations

Title

Config file reference

Open

Configuration reference

Title

Provider pacing and retries

Open

Rate limiting and retries

Security and configuration

Capability	Supported	Notes
Encrypted stored secrets	Yes	Fernet encryption
Generated local master key	Yes	Stored as .cw_master_key with restrictive permissions when possible
External master key	Yes	CW_CONFIG_KEY or CROSSWATCH_CONFIG_KEY
Secret redaction	Yes	Tokens, API keys, passwords, session IDs, and webhook identifiers
Optional local UI login	Yes	Username and password
Password hashing	Yes	PBKDF2 SHA256, 260000 iterations
Remember session	Yes	Configurable duration
Multiple login sessions	Yes
HTTP interface	Yes
HTTPS interface	Yes
Automatic self-signed certificate	Yes	Configurable hostname and validity
Custom certificate and key	Yes
Provider SSL verification	Yes	Configurable for local server providers
Atomic configuration writes	Yes	Temporary file replacement
Configuration backup before reset	Yes
Backup path validation	Yes	Restricts access to managed backup paths
Capture path validation	Yes	Restricts access to managed capture paths

Runtime and storage

Area	Default or support
Persistent configuration root	/config in the container image
Main configuration	/config/config.json
Main sync state	/config/state.json
Manual policy state	/config/state.manual.json
Provider runtime state	/config/.cw_state
Local CrossWatch tracker	/config/.cw_provider
Local tracker snapshots	/config/.cw_provider/snapshots
Captures	/config/snapshots
Backups	/config/backups
Sync reports	/config/sync_reports
Runtime debug logging	Supported
HTTP access logging	Supported
Sync module debug logging	Supported
Provider request rate limits	Supported
Provider retry budgets	Supported
Usage telemetry	Enabled by default, configurable

Important limitations

Destructive removals stay off by default for a reason. Test first with dry runs.

1. There is no general playlist sync feature.
2. Jellyfin and Emby ratings are not currently exposed as sync features.
3. Jellyfin and Emby watchlists are emulated through Favorites, Playlist, or Collections.
4. Jellyfin and Emby Playlist watchlist mode is episode-oriented and cannot represent shows.
5. Tautulli is a read-only history source.
6. AniList only supports anime watchlist and ratings workflows.
7. TMDb only supports watchlist and ratings sync.
8. Trakt, SIMKL, and MDBList do not participate in normal pair-based progress sync, even though they are supported by the Playback Progress Manager.
9. PublicMetaDB writes require TMDb identity, and progress writes require duration.
10. Plex progress removal may be limited by Plex behavior.
11. Destructive removals are globally disabled by default, but a pair can explicitly enable them.
12. Mirror delete mode is destructive and should be used only when the source must be authoritative.
13. Drop guard and mass-deletion settings should be configured deliberately, especially during the first sync.
14. Plex fallback GUID searching increases runtime and resource use and is intended as a temporary recovery option.
15. Provider APIs, account permissions, rate limits, and upstream behavior can still prevent an operation that the CrossWatch adapter implements.