> 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-clients/kodi/kodi-add-on/install-and-connect.md).

# Install and connect

Install the beta, pair Kodi with CrossWatch, and configure the connection.

### Requirements

| Requirement | Details                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| Kodi        | Kodi 21 (Omega). Earlier versions are not supported. Later versions have not been tested.                     |
| CrossWatch  | v0.13.3 or later. Rating needs v0.13.4. Choosing people from CrossWatch needs v0.13.5.                        |
| Network     | Kodi must reach CrossWatch. CrossWatch needs Kodi only for the optional Link shortcut.                        |
| HTTPS       | Use a certificate from a public authority, such as Let's Encrypt. Self-signed certificates are not supported. |

Include `https://` when using HTTPS. Without a scheme, the add-on assumes `http://`.

Kodi's web server and JSON-RPC interface are not required. Only Link uses them.

### Install

#### Beta

The add-on is not in Kodi's official repository yet. Install the beta from a [GitHub release](https://github.com/crosswatch-app/kodi-addon/releases):

1. Download `service.crosswatch-*.zip` from the release assets.
2. In Kodi, turn on **Settings** → **System** → **Add-ons** → **Unknown sources**. Choose **Yes**.
3. Open **Add-ons**. Select the add-on browser, then **Install from zip file**. Pick the ZIP.
4. Continue with [Pairing](#pairing).

A ZIP installation does not update automatically. Install each new ZIP over the current version.

#### Later

After beta, the add-on reaches the author's repository first, then Kodi's official repository. Both provide automatic updates.

### Pairing

Pairing configures the CrossWatch address and token. Do this for each Kodi device and Kodi profile.

1. Open CrossWatch in a browser. Have its address ready, for example `192.168.1.10:8787`.
2. In CrossWatch, open **Settings → Connections → Media clients → Kodi**. Select **Add-on**, then **Connect add-on**. CrossWatch shows a pairing code.
3. In Kodi, open **Add-ons** → **My add-ons** → **Services** → **CrossWatch** → **Configure**. In **CrossWatch**, select **Pair with CrossWatch**.
4. Enter the CrossWatch address. `http://` is assumed if omitted. A trailing slash or full webhook URL also works.
5. Enter the pairing code. It has six letters and digits, lasts ten minutes, and works once. Case and spaces do not matter.

Kodi confirms the instance. **Status** reads `Paired with <instance> at <address>`. Reporting starts immediately.

Selecting **Pair** closes settings and saves other changes. Leaving either field empty cancels pairing.

#### Pairing errors

| Message                                           | What to do                                                                              |
| ------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Code wrong or expired                             | Get a new code in CrossWatch. Confirm the add-on is enabled for this Kodi profile.      |
| Too many tries                                    | Wait a few minutes, then pair with a new code.                                          |
| Can't reach CrossWatch at `<address>`             | Check the address, port, and network access from Kodi.                                  |
| Pairing failed: CrossWatch answered HTTP `<code>` | Check the CrossWatch log.                                                               |
| The certificate was not accepted                  | Use a public certificate. Use `http://` on a trusted home network.                      |
| Not a CrossWatch address                          | Use an `http://` or `https://` address. Put a URL containing `?token=` in manual setup. |

#### Status

* `Paired with <instance> at <address>` means CrossWatch answered at least once.
* `Not paired` means no address or token is configured.

The status records the last successful response. It does not test the live connection.

#### Link shortcut

CrossWatch can link the add-on without a code when it already controls Kodi through JSON-RPC. Start **Link add-on** in CrossWatch.

**Yes** connects as pairing does. **No**, or no response within 60 seconds, changes nothing. Most households should use pairing.

#### Move or unpair

Pair directly with another CrossWatch instance. You do not need to unpair first. Completed watches queued for the old instance are discarded, because they use its token.

**Unpair** stops reporting and clears the address and token. Queued completed watches remain. They send if you pair again with the same instance and token.

### Manual setup

Switch Kodi settings to the **Advanced** level to show these settings:

* **Webhook URL**: the complete endpoint, for example `http://192.168.1.10:8787/webhook/kodiwatcher`.
* **Webhook token**: the token from CrossWatch.

CrossWatch's **Manual setup** gives a URL ending in `?token=`. Paste it into **Webhook URL**. The add-on moves the token to **Webhook token** when you confirm. It sends the token only in a request header.

Pairing fills in both fields. Editing either changes the paired connection.

{% hint style="warning" %}
The add-on URL contains a secret token. Treat it like a password.
{% endhint %}


---

# 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-clients/kodi/kodi-add-on/install-and-connect.md?ask=<question>&goal=<user_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.
