> 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/crosswatch/settings/connections/media-servers/tofa.md).
# Tofa
Connect Tofa and choose the household profiles and libraries to use.
{% tabs %}
{% tab title="End users" %}
Tofa is a self-hosted media server for movies and shows. CrossWatch connects through your Tofa account and keeps each household profile's data separate.
{% hint style="warning" %}
Tofa support is **experimental**. Update your Tofa server if CrossWatch reports that required capabilities are missing.
{% endhint %}
### What CrossWatch can sync
**Read** brings data into CrossWatch; **Write** sends changes to this provider.
| Feature | Read | Write | Notes |
| ---------- | ---- | ----- | ----------------------------------------------------------------------------- |
| Watchlist | Yes | Yes | Movies and shows, including titles outside your library. |
| History | Yes | Yes | Library movies and episodes; no separate rewatch events. |
| Ratings | No | No | Unsupported. |
| Progress | Yes | Yes | Library movies and episodes; positions must be at least one minute. |
| Playlists | No | No | Unsupported. |
| Collection | Yes | No | Read-only library inventory: movies, shows and episodes. Optional media info. |
**Live scrobbling:** Watcher source and scrobble destination. Native webhook input is unsupported.
See the [synchronization guide](/crosswatch/settings/synchronization/media-servers/tofa.md) for matching rules and feature restrictions.
### Before you start
* Have your Tofa server set up and accessible from the machine running CrossWatch. CrossWatch connects directly to the server; it does not use Tofa's remote relay.
* Have access to your Tofa account and the PIN for any protected household profile you want to use.
### Connect Tofa
1. Go to **Settings → Connections → Media servers → Tofa**.
2. Enter your **Server URL**, for example `http://192.168.1.10:33333`. Use your server's actual address and port.
3. For HTTPS with a trusted certificate, enable **Verify SSL**. It is off by default.
4. Click **Connect Tofa**. The approval window first shows a waiting screen, then your device code before opening the Tofa approval page.
5. Approve the code while signed in to your Tofa account. If the popup is blocked, use the link or QR code shown in CrossWatch.
6. Choose the **Tofa profile** to use. Enter its **Profile PIN** if requested, then click **Save**.
CrossWatch stores the session and profile unlock returned by Tofa, not your password or PIN. It renews the session automatically. If a profile needs unlocking again, enter its PIN and save.
### Household profiles
For your own account, use the profile selected under **Authentication**.
To include other people, open **Identities**, select their household profiles, enter any required PINs, and save. In a sync pair, open **Media servers**, enable **Identities**, then check and save the links between people. For a Watcher route, enable **Identities** on its **Route** tab.
Matching names are suggestions; check each link before saving. Once Identities is enabled, only linked people are included. See [Multiple media server users](/crosswatch/settings/connections/media-servers/multiple-media-server-users.md).
For a separate tracker account, create another Tofa connection with that person's household profile and pair it with their tracker connection.
### Whitelisting
Open **Whitelisting** to select libraries separately for **History**, **Progress**, **Collections**, and **Scrobble**. Scrobble controls the Watcher source. Watchlist is not restricted to your libraries.
Review the library selections under **Providers** in each sync pair too. For a Tofa scrobble destination, review the route's destination libraries; without a route selection, the connection's History or Progress selection applies.
### Recommended setup
1. Create a one-way pair, such as **Tofa → Trakt**.
2. Enable one feature and turn on **Dry run**.
3. Review the proposed changes, then turn off Dry run to sync.
4. Add more features once the results match what you expect.
### Watcher and scrobbling
* **As a source**, Tofa reports playback for the connected profile or the identities linked in the route. **Detect manual marks** also forwards items you mark watched by hand.
* **Watched threshold:** the route's **Options** shows Tofa's watched rule alongside **Mark as watched at**. A lower route threshold can mark the destination watched before Tofa. If Tofa confirms completion during playback first, CrossWatch can forward that completion even when the route threshold is higher.
* **Change Tofa's rule:** when the percentages differ, use the button labelled with the route percentage, such as **Apply 90% to Tofa**. Tofa offers 70, 75, 80, 85, 90 and 95%. Credits count only when Tofa's rule and the confirmed playback state support it.
* **As a destination**, Tofa receives resume positions and completed watches for matching library items. Resume writes need a known runtime and a position of at least one minute. CrossWatch avoids overwriting an active Tofa playback session.
### Troubleshooting
| Problem | What to do |
| --------------------------------- | ------------------------------------------------------------------------------ |
| Server cannot be reached | Check the server URL and port from the machine running CrossWatch. |
| Server setup is incomplete | Finish setup in Tofa, then connect again. |
| Required capabilities are missing | Update Tofa and reconnect. |
| SSL check failed | Check that the certificate is valid and trusted by the CrossWatch host. |
| Tofa session ended | Reconnect the Tofa connection. |
| Enter the Tofa profile PIN again | Enter the PIN under Authentication or for the affected identity, then save. |
| Not in library | Check that the title exists in Tofa and is included in the selected libraries. |
| Tofa no longer has this file | Let Tofa finish its library scan, then retry the sync. |
| {% endtab %} | |
{% tab title="Power users" %}
### Matching and library behavior
Watchlist writes need a TMDb ID. History and progress match library items using TMDb, IMDb or TVDB IDs; episodes also need their season and episode numbers. File-path and fuzzy title matching are not supported.
See the synchronization guide for edition handling, history removal, progress restrictions and Collection scope.
{% content-ref url="/pages/lWlktkAsHe0wvPRY1uzE" %}
[Tofa](/crosswatch/settings/synchronization/media-servers/tofa.md)
{% endcontent-ref %}
### Disconnecting
Disconnecting removes the saved session from CrossWatch. Remove the device in your Tofa account too if you no longer want it authorized.
{% content-ref url="/pages/n6LWZk2H6QOtQdNneQFr" %}
[Multiple media server users](/crosswatch/settings/connections/media-servers/multiple-media-server-users.md)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}
---
# 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/crosswatch/settings/connections/media-servers/tofa.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.
