### Start Comet Instance

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Start your Comet instance using the uvicorn runner or Docker Compose. Check logs for 'CometNet started' confirmation.

```bash
uv run python -m comet.main
```

```bash
docker compose up -d
```

--------------------------------

### Install Stremio Add-on

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

Event listener for an install button click that retrieves settings, generates the installation manifest URL, and redirects the user's browser to initiate the Stremio add-on installation.

```javascript
installButton.addEventListener("click", () => {
  const settings = getSettings();
  const manifestUrl = getManifestUrl(settings, true);
  window.location.href = manifestUrl;
  console.log(`Installing manifest URL: ${manifestUrl}`);
  installAlert.toast();
});
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/g0ldyy/comet/blob/main/README.md

Install project dependencies using the 'uv' package manager. Ensure 'uv' is installed before running this command.

```bash
pip install uv
uv sync
```

--------------------------------

### Setup Kodi Integration with Code

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

Handles the process of setting up Kodi integration by sending a hexadecimal setup code and the generated manifest URL to the server. Includes error handling and success feedback.

```javascript
async function setupKodiWithCode(rawCode) {
  const code = rawCode.trim().toLowerCase();
  if (!/^\\\[0-9a-f\\\\]{6,16}$/.test(code)) {
    showKodiError("Kodi setup code must be a 6–16 character hexadecimal value.");
    return;
  }
  const settings = getSettings();
  const manifestUrl = getKodiManifestUrl(settings);
  const response = await fetch("/kodi/associate_manifest", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      code: code,
      manifest_url: manifestUrl,
    }),
  });
  if (!response.ok) {
    let errorMessage = "Failed to setup Kodi.";
    try {
      const errorData = await response.json();
      if (errorData.detail) {
        errorMessage = errorData.detail;
      }
    } catch (error) {
      console.error("Failed to parse Kodi setup error:", error);
    }
    showKodiError(errorMessage);
    return;
  }
  kodiAlertText.textContent = "Kodi setup completed successfully.";
  kodiAlert.toast();
  return true;
}
```

--------------------------------

### Start Background Scraper

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/admin_dashboard.html

Initiates the background scraper. Sends a POST request to the start endpoint and displays a success message.

```javascript
async function startBackgroundScraper() {
  await triggerBackgroundScraperAction(
    "start",
    "Background scraper starting",
  );
}
```

--------------------------------

### Start Comet Application

Source: https://github.com/g0ldyy/comet/blob/main/README.md

Run the Comet application using 'uv' to manage the Python environment. This command starts the main Comet process.

```bash
uv run python -m comet.main
```

--------------------------------

### Start Docker Compose Stack

Source: https://github.com/g0ldyy/comet/blob/main/docs/beginner/01-get-started-docker.md

Starts the Comet and PostgreSQL services in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Associate Kodi Pairing Code with Manifest

Source: https://context7.com/g0ldyy/comet/llms.txt

This endpoint is called by the browser-based configuration UI after user setup is complete. It links the generated setup code with the manifest URL.

```bash
curl -X POST http://localhost:8000/kodi/associate_manifest \
  -H "Content-Type: application/json" \
  -d '{
    "code": "A7B3F2K9",
    "manifest_url": "http://localhost:8000/eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCJ9/manifest.json"
  }'
```

--------------------------------

### Check Cometnet Container Logs

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/docker.md

Use this command to view the logs of the cometnet container when it fails to start.

```bash
docker compose logs cometnet
```

--------------------------------

### GET /configure

Source: https://context7.com/g0ldyy/comet/llms.txt

Renders the interactive HTML configuration page. Requires a session cookie if CONFIGURE_PAGE_PASSWORD is set. Allows configuration of debrid services, filters, and generates Stremio install URLs.

```APIDOC
## GET /configure — Web Configuration UI

Renders the interactive HTML configuration page. When `CONFIGURE_PAGE_PASSWORD` is set, requires a session cookie obtained via `POST /configure/login`. The page lets users configure debrid services, RTN ranking, language/resolution filters, result format, etc., and generates an install URL / manifest URL for Stremio.

### Request Example
```bash
# Open config page in browser
open http://localhost:8000/configure

# With existing config pre-filled
open http://localhost:8000/eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCJ9/configure

# Authenticate when CONFIGURE_PAGE_PASSWORD is set
curl -c cookies.txt -X POST http://localhost:8000/configure/login \
  -d "password=mysecret&next=/configure"
# Redirects to /configure with session cookie set
```
```

--------------------------------

### GET /admin/api/logs

Source: https://context7.com/g0ldyy/comet/llms.txt

Returns buffered application logs starting from a specified Unix timestamp. Use `since=0` to retrieve all recent logs.

```APIDOC
## GET /admin/api/logs — Live Application Logs

Returns buffered application logs since a given Unix timestamp (use `since=0` for all recent logs).

### Method
GET

### Endpoint
/admin/api/logs

#### Query Parameters
- **since** (integer) - Required - Unix timestamp to fetch logs from. Use 0 for all recent logs.

### Response
#### Success Response (200)
- **logs** (array) - A list of log entries.
- **total_logs** (integer) - The total number of logs available.
- **new_logs** (integer) - The number of new logs returned in this request.

### Response Example
```json
{
  "logs": [
    {"created": 1717000010.5, "levelname": "INFO", "message": "🔍 Starting search for (tt0816692) Interstellar"},
    {"created": 1717000011.1, "levelname": "INFO", "message": "📦 Found cached torrents: 42"}
  ],
  "total_logs": 250,
  "new_logs": 2
}
```
```

--------------------------------

### Get Live Application Logs

Source: https://context7.com/g0ldyy/comet/llms.txt

Retrieve buffered application logs since a specified Unix timestamp. Use `since=0` to get all recent logs. Requires an admin session cookie.

```bash
curl -b admin_cookies.txt "http://localhost:8000/admin/api/logs?since=1717000000"
```

--------------------------------

### Enable CometNet (Home User)

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Add these settings to your .env file to enable CometNet for a single instance setup at home. Ensure FastAPI workers are set to 1.

```env
COMETNET_ENABLED=True
FASTAPI_WORKERS=1
```

--------------------------------

### Docker Compose Volume Configuration

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/docker.md

Example of configuring persistent volumes for CometNet data, ensuring state persistence.

```yaml
volumes:
  - ./data:/app/data  # or named volume: comet_data:/app/data
```

--------------------------------

### Associate Kodi Code with Manifest

Source: https://context7.com/g0ldyy/comet/llms.txt

Links a generated Kodi setup code with the Comet manifest URL, typically called after user configuration in the browser.

```APIDOC
## POST /kodi/associate_manifest

### Description
Links the setup code to the b64config-embedded manifest URL. Called by the browser-based configure UI.

### Method
POST

### Endpoint
/kodi/associate_manifest

### Request Body
- **code** (string) - Required - The Kodi setup code.
- **manifest_url** (string) - Required - The URL of the Comet manifest.

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the association, e.g., "success".

### Request Example
```json
{
  "code": "A7B3F2K9",
  "manifest_url": "http://localhost:8000/eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCJ9/manifest.json"
}
```

### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Kodi Integration Endpoints

Source: https://github.com/g0ldyy/comet/blob/main/docs/advanced/06-http-api-reference.md

Endpoints for integrating with Kodi, including setup code generation and manifest association.

```APIDOC
## Kodi Integration Endpoints

### POST /kodi/generate_setup_code
Generates a setup code for Kodi integration.

### POST /kodi/associate_manifest
Associates a manifest with Kodi.

### GET /kodi/get_manifest/{code}
Retrieves the manifest associated with a given code.
```

--------------------------------

### Display Kodi Setup Error

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

A utility function to display error messages related to Kodi setup. It targets a specific HTML element to show the error to the user.

```javascript
function showKodiError(message) {
  const errorAlert = document.getElementById("kodiErrorAlert");
  const errorText = document.getElementBy
```

--------------------------------

### POST /admin/api/background-scraper/start

Source: https://context7.com/g0ldyy/comet/llms.txt

Starts the background scraper worker, which proactively pre-caches torrent metadata for recently searched media. This operation requires an admin session cookie.

```APIDOC
## POST /admin/api/background-scraper/start — Start Background Scraper

Starts the background scraper worker that proactively pre-caches torrent metadata for recently searched media. Requires admin session cookie.

### Method
POST

### Endpoint
/admin/api/background-scraper/start

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message describing the result of the operation.

### Request Example
```bash
curl -b admin_cookies.txt -X POST http://localhost:8000/admin/api/background-scraper/start
# {"success": true, "message": "Background scraper starting"}

# Stop it
curl -b admin_cookies.txt -X POST http://localhost:8000/admin/api/background-scraper/stop
# {"success": true, "message": "Background scraper stopped"}
```
```

--------------------------------

### Verify CometNet Status in Logs

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Check the Comet instance logs for confirmation messages indicating CometNet has started successfully and is connected to peers.

```text
CometNet started - Node ID: abc123...
Discovery service started with 2 known peers
Connected to peer def456...
```

--------------------------------

### Get Unconfigured Add-on Manifest

Source: https://context7.com/g0ldyy/comet/llms.txt

Retrieves the Stremio add-on manifest. Without a configuration, it indicates that the user needs to reconfigure the add-on.

```bash
curl http://localhost:8000/manifest.json
# {
#   "id": "stremio.comet.fast",
#   "name": "❌ | Comet",
#   "description": "⚠️ OBSOLETE CONFIGURATION ...",
#   "version": "2.0.0",
#   "resources": [{"name":"stream","types":["movie","series"],"idPrefixes":["tt","kitsu"]}],
#   "types": ["movie","series","anime","other"],
#   "behaviorHints": {"configurable": true, "configurationRequired": false}
# }
```

--------------------------------

### Get Configured Add-on Manifest

Source: https://context7.com/g0ldyy/comet/llms.txt

Retrieves the Stremio add-on manifest with a valid base64 configuration. The manifest name reflects the configured debrid service(s).

```bash
curl http://localhost:8000/eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCIsImRlYnJpZEFwaUtleSI6IkFCQ0QifQ/manifest.json
# {
#   "id": "stremio.comet.fast",
#   "name": "RD | Comet",
#   "version": "2.0.0",
#   "resources": [...],
#   ...
# }
```

--------------------------------

### Get Application Metrics

Source: https://context7.com/g0ldyy/comet/llms.txt

Retrieve a JSON snapshot of database statistics, including torrent counts, search activity, and debrid cache status. This endpoint is cached.

```bash
curl -b admin_cookies.txt http://localhost:8000/admin/api/metrics
```

--------------------------------

### Build Comet Add-on and Repository

Source: https://github.com/g0ldyy/comet/blob/main/kodi/README.md

Use 'make' to perform a full build of both the add-on and its update repository. This command is typically run from the 'kodi' directory.

```sh
cd kodi
make
```

--------------------------------

### Setup Auto-Refresh for Dashboard Tabs

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/admin_dashboard.html

Configures interval-based auto-refreshing for specific dashboard tabs ('connections', 'logs', 'background-scraper', 'cometnet'). It stops any existing intervals before starting a new one based on the selected tab and the configured refresh interval.

```javascript
function setupAutoRefreshForTab(tab) {
  if (!document.getElementById("auto-refresh").checked) return;
  stopAllIntervals();
  const interval = parseInt(
    document.getElementById("refresh-interval").value,
  );
  switch (tab) {
    case "connections":
      connectionsInterval = setInterval(loadConnections, 5000);
      break;
    case "logs":
      logsInterval = setInterval(loadLogs, interval);
      break;
    case "background-scraper":
      backgroundScraperInterval = setInterval(
        loadBackgroundScraperData,
        Math.max(5000, interval),
      );
      break;
    case "cometnet":
      cometnetInterval = setInterval(loadCometNetStats, 10000);
      break;
  }
}
```

--------------------------------

### Initialize Custom Elements and Populate Settings

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

Waits for custom elements to be defined and then populates settings for resolutions, result formats, and languages. It also includes a live preview for the result format.

```javascript
const languagesEmojis = {
  "multi": "🌎",
  "en": "🇬🇧", // English
  "ja": "🇯🇵", // Japanese
  "zh": "🇨🇳", // Chinese
  "ru": "🇷🇺", // Russian
  "ar": "🇸🇦", // Arabic
  "pt": "🇵🇹", // Portuguese
  "es": "🇪🇸", // Spanish
  "fr": "🇫🇷", // French
  "de": "🇩🇪", // German
  "it": "🇮🇹", // Italian
  "ko": "🇰🇷", // Korean
  "hi": "🇮🇳", // Hindi
  "bn": "🇧🇩", // Bengali
  "pa": "🇵🇰", // Punjabi
  "mr": "🇮🇳", // Marathi
  "gu": "🇮🇳", // Gujarati
  "ta": "🇮🇳", // Tamil
  "te": "🇮🇳", // Telugu
  "kn": "🇮🇳", // Kannada
  "ml": "🇮🇳", // Malayalam
  "th": "🇹🇭", // Thai
  "vi": "🇻🇳", // Vietnamese
  "id": "🇮🇩", // Indonesian
  "tr": "🇹🇷", // Turkish
  "he": "🇮🇱", // Hebrew
  "fa": "🇮🇷", // Persian
  "uk": "🇺🇦", // Ukrainian
  "el": "🇬🇷", // Greek
  "lt": "🇱🇹", // Lithuanian
  "lv": "🇱🇻", // Latvian
  "et": "🇪🇪", // Estonian
  "pl": "🇵🇱", // Polish
  "cs": "🇨🇿", // Czech
  "sk": "🇸🇰", // Slovak
  "hu": "🇭🇺", // Hungarian
  "ro": "🇷🇴", // Romanian
  "bg": "🇧🇬", // Bulgarian
  "sr": "🇷🇸", // Serbian
  "hr": "🇭🇷", // Croatian
  "sl": "🇸🇮", // Slovenian
  "nl": "🇳🇱", // Dutch
  "da": "🇩🇰", // Danish
  "fi": "🇫🇮", // Finnish
  "sv": "🇸🇪", // Swedish
  "no": "🇳🇴", // Norwegian
  "ms": "🇲🇾", // Malay
  "la": "💃🏻" // Latino
};
let defaultResultFormat = [];
const ALL_RESOLUTIONS = ["r2160p", "r1440p", "r1080p", "r720p", "r576p", "r480p", "r360p", "r240p", "unknown"];
(async () => {
  await Promise.allSettled([
    customElements.whenDefined("sl-button"),
    customElements.whenDefined("sl-alert"),
    customElements.whenDefined("sl-select"),
    customElements.whenDefined("sl-input"),
    customElements.whenDefined("sl-option"),
    customElements.whenDefined("sl-icon"),
    customElements.whenDefined("sl-checkbox")
  ]);
  const webConfig = {{ webConfig| tojson }};
  const resolutionsSelect = document.getElementById("resolutions");
  resolutionsSelect.value = ALL_RESOLUTIONS;
  populateSelect("resultFormat", webConfig.resultFormat);
  defaultResultFormat = webConfig.resultFormat;
  const resultFormatSelect = document.getElementById("resultFormat");
  resultFormatSelect.value = defaultResultFormat;

  // Live preview for result format
  function updateResultFormatPreview() {
    const sel = document.getElementById("resultFormat");
    const raw = sel.value;
    const selected = Array.isArray(raw) ? raw : (raw ? [raw] : []);
    const hasAll = selected.includes("all");
    const S = {
      title: "📄 Movie.Title.2024.1080p.BluRay.x264-GROUP",
      video: "📹 H.264 • HDR • 10bit",
      audio: "🔊 DDP5.1 • Atmos",
      quality: "⭐ BluRay",
      group: "🏷️ YTS",
      seeders: "👤 1234",
      size: "💾 12.5 GB",
      tracker: "🔎 Yggrasil",
      languages: "🇬🇧/🇫🇷"
    };
    const c = {};
    if (hasAll || selected.includes("title")) c.title = S.title;
    if (hasAll || selected.includes("video_info")) c.video = S.video;
    if (hasAll || selected.includes("audio_info")) c.audio = S.audio;
    if (hasAll || selected.includes("quality_info")) c.quality = S.quality;
    if (hasAll || selected.includes("release_group")) c.group = S.group;
    if (hasAll || selected.includes("seeders")) c.seeders = S.seeders;
    if (hasAll || selected.includes("size")) c.size = S.size;
    if (hasAll || selected.includes("tracker")) c.tracker = S.tracker;
    if (hasAll || selected.includes("languages")) c.languages = S.languages;

    const lines = [];
    if (c.title) lines.push(c.title);
    const va = [c.video, c.audio].filter(Boolean);
    if (va.length) lines.push(va.join(" | "));
    const qg = [c.quality, c.group].filter(Boolean);
    if (qg.length) lines.push(qg.join(" | "));
    const info = [c.seeders, c.size, c.tracker].filter(Boolean);
    if (info.length) lines.push(info.join(" "));
    if (c.languages) lines.push(c.languages);

    document.getElementById("resultFormatPreview").textContent = lines.length ? lines.join("\n") : "Empty result format configuration";
  }
  resultFormatSelect.addEventListener("sl-change", updateResultFormatPreview);
  updateResultFormatPreview();

  // try populate the form from previous settings
  try {
    const settings = getSettingsFromUrl();
    if (settings != null) {
      populateFormFromSettings(settings);
    }
  } catch (error) {
    console.log("Failed to retrieve or parse settings from URL:", error);
  }

  // Populate language selects
  populateSelect("languages_required", Object.keys(languagesEmojis));
  populateSelect("languages_allowed", Object.keys(languagesEmojis));
  populateSelect("languages_excluded", Object.keys(languagesEmojis));
  populateSelect("languages_preferred", Object.keys(languagesEmojis));

  document.body.classList.add("ready");
})();
```

--------------------------------

### Configure Bootstrap Nodes

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/cometnet.md

Provide a JSON array of public entry points for network discovery. Format: '["wss://node1:8765", "wss://node2:8765"]'.

```env
COMETNET_BOOTSTRAP_NODES='["wss://bootstrap.comet.example.com:8765"]'
```

--------------------------------

### Initialize Dashboard and Load Connections

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/admin_dashboard.html

Sets up event listeners for various custom elements and initializes the dashboard by loading connections. It also ensures the background scraper ticker is running and renders its next cycle status.

```javascript
document.addEventListener("DOMContentLoaded", async () => { await Promise.allSettled(
    customElements.whenDefined("sl-tab-group"),
    customElements.whenDefined("sl-tab"),
    customElements.whenDefined("sl-tab-panel"),
    customElements.whenDefined("sl-button"),
    customElements.whenDefined("sl-icon"),
    customElements.whenDefined("sl-spinner"),
    customElements.whenDefined("sl-switch"),
    customElements.whenDefined("sl-select"),
    customElements.whenDefined("sl-option"),
  );
  document.body.classList.add("ready");
  initializeDashboard();
});
let currentMetricsData = null;
let connectionsInterval = null;
let logsInterval = null;
let cometnetInterval = null;
let backgroundScraperInterval = null;
let backgroundScraperNextCycleTicker = null;
let backgroundScraperNextCycleState = "stopped";
let backgroundScraperNextCycleTargetTs = null;
const backgroundScraperCycleIntervalSeconds = Number( {{ background_scraper_interval }} );
let lastLogTimestamp = 0;
let currentTab = "connections"; // Track current active tab
// Pools state
let poolsCache = [];
let currentPoolFilter = "subscribed";
let poolSearchTerm = "";
// Peer cache for cross-referencing
let peersCache = [];
function initializeDashboard() {
  loadConnections();
  ensureBackgroundScraperNextCycleTicker();
  renderBackgroundScraperNextCycle();
  setupAutoRefreshForTab("connections");
  document
    .getElementById("clear-logs")
    .addEventListener("click", clearLogsDisplay);
  document
    .getElementById("download-logs")
    .addEventListener("click", downloadLogs);
  document
    .getElementById("auto-refresh")
    .addEventListener("sl-change", toggleAutoRefresh);
  document
    .getElementById("refresh-interval")
    .addEventListener("sl-change", updateRefreshInterval);
  document
    .getElementById("hide-api-logs")
    .addEventListener("sl-change", toggleApiLogsVisibility);
  document
    .querySelector("sl-tab-group")
    .addEventListener("sl-tab-show", handleTabChange);
  const poolSearch = document.getElementById("pool-search");
  if (poolSearch) {
    poolSearch.addEventListener("sl-input", () => {
      poolSearchTerm = poolSearch.value.trim().toLowerCase();
      renderPoolsList();
    });
  }
}
```

--------------------------------

### Create Working Directory

Source: https://github.com/g0ldyy/comet/blob/main/docs/beginner/01-get-started-docker.md

Creates a new directory for your Comet deployment and navigates into it.

```bash
mkdir comet-deploy
cd comet-deploy
```

--------------------------------

### Configure Advertise URL

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/cometnet.md

Required if behind a reverse proxy. Set your public WebSocket URL (e.g., `wss://comet.example.com/cometnet/ws`).

```env
COMETNET_ADVERTISE_URL=wss://comet.example.com/cometnet/ws
```

--------------------------------

### View Comet Logs

Source: https://github.com/g0ldyy/comet/blob/main/docs/beginner/01-get-started-docker.md

Follows the logs for the Comet service to confirm startup information.

```bash
docker compose logs -f comet
```

--------------------------------

### Get CometNet Stats

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/docker.md

Command to retrieve statistics from the CometNet service.

```bash
curl http://localhost:8766/stats
```

--------------------------------

### Configure Key Password

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/cometnet.md

Set an optional password to encrypt your private key on disk.

```env
COMETNET_KEY_PASSWORD=your_secret_password
```

--------------------------------

### Configure CometNet Entry Points

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Configure how your CometNet instance connects to the network. Use bootstrap nodes if available, or direct peer connections.

```env
# Option 1: Bootstrap nodes (if available)
COMETNET_BOOTSTRAP_NODES='["wss://bootstrap.example.com:8765"]'

# Option 2: Direct peer connection
COMETNET_MANUAL_PEERS='["ws://friend-comet.example.com:8765"]'
```

--------------------------------

### Control Background Scraper

Source: https://context7.com/g0ldyy/comet/llms.txt

Start or stop the background scraper worker, which proactively pre-caches torrent metadata. Requires an admin session cookie.

```bash
curl -b admin_cookies.txt -X POST http://localhost:8000/admin/api/background-scraper/start
```

```bash
curl -b admin_cookies.txt -X POST http://localhost:8000/admin/api/background-scraper/stop
```

--------------------------------

### Configure Private Network Joining

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Enable CometNet and configure private network settings including ID and password. Add the admin's node as a manual peer to join the private network.

```env
COMETNET_ENABLED=True
FASTAPI_WORKERS=1

COMETNET_PRIVATE_NETWORK=True
COMETNET_NETWORK_ID=my-private-network
COMETNET_NETWORK_PASSWORD=the-shared-secret

# Add the admin's node as a peer
COMETNET_MANUAL_PEERS='["wss://admin-node.example.com:8765"]'
```

--------------------------------

### Troubleshoot No Peers Connecting

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

If no peers are connecting, verify that port 8765 is reachable, `COMETNET_ADVERTISE_URL` is correctly set, and UPnP is enabled if you are behind NAT.

```text
1. Check if port 8765 is reachable (use a port checker tool)
2. Verify `COMETNET_ADVERTISE_URL` is set correctly
3. Enable UPnP if behind NAT: `COMETNET_UPNP_ENABLED=True`
```

--------------------------------

### Generate Stremio Manifest URL

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

Generates the appropriate manifest URL for Stremio, differentiating between default and custom configurations. Includes logic for installation URLs.

```javascript
function getManifestUrl(settings, forInstall = false) {
  const isDefault = isDefaultConfig(settings);
  const host = window.location.host;
  if (isDefault) {
    // Default config: use public manifest URL (better CDN caching)
    return forInstall ? `stremio://${host}${stremioApiPrefix}/manifest.json` : `${window.location.origin}${stremioApiPrefix}/manifest.json`;
  } else {
    // Custom config: use b64config in URL
    const settingsString = btoa(JSON.stringify(settings));
    return forInstall ? `stremio://${host}${stremioApiPrefix}/${settingsString}/manifest.json` : `${window.location.origin}${stremioApiPrefix}/${settingsString}/manifest.json`;
  }
}
```

--------------------------------

### Open Web Configuration UI

Source: https://context7.com/g0ldyy/comet/llms.txt

Access the interactive HTML configuration page. An optional pre-filled configuration can be provided in the URL. Authentication is required if CONFIGURE_PAGE_PASSWORD is set.

```bash
open http://localhost:8000/configure
```

```bash
open http://localhost:8000/eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCJ9/configure
```

```bash
curl -c cookies.txt -X POST http://localhost:8000/configure/login \
  -d "password=mysecret&next=/configure"
```

--------------------------------

### Comet Login Page Initialization and Form Handling

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/admin_login.html

Initializes custom elements and adds a 'ready' class to the body once they are defined. It also handles form submission by setting a loading state on the submit button.

```javascript
document.addEventListener("DOMContentLoaded", async () => { await Promise.allSettled(\[ customElements.whenDefined("sl-button"), customElements.whenDefined("sl-alert"), customElements.whenDefined("sl-input"), customElements.whenDefined("sl-icon"), \]); document.body.classList.add("ready"); // Handle form submission with loading state const form = document.querySelector("form"); const submitButton = document.querySelector('sl-button[type="submit"]'); form.addEventListener("submit", function () { submitButton.loading = true; submitButton.textContent = submitButton.dataset.loadingText || "Signing In..."; }); });
```

--------------------------------

### Run DB Import/Export CLI

Source: https://github.com/g0ldyy/comet/blob/main/docs/advanced/05-database-and-operations.md

Use this command to access the database CLI for operations like listing tables, exporting, or importing data. Ensure Python is in your PATH.

```bash
python -m comet.db_cli
```

--------------------------------

### Open Firewall Port

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Ensure port 8765 is open on your server's firewall to allow incoming CometNet connections. This example uses UFW.

```bash
# Example for UFW
sudo ufw allow 8765/tcp
```

--------------------------------

### Check Background Scraper Status

Source: https://context7.com/g0ldyy/comet/llms.txt

Use this endpoint to get the current status of the background scraper, including its running state, queue size, and any recent errors.

```bash
curl -b admin_cookies.txt http://localhost:8000/admin/api/background-scraper/status
```

--------------------------------

### Get Active Debrid Stream Connections

Source: https://context7.com/g0ldyy/comet/llms.txt

List active proxied debrid stream connections with real-time bandwidth metrics. Requires an admin session cookie.

```bash
curl -b admin_cookies.txt http://localhost:8000/admin/api/connections
```

--------------------------------

### Load and Render Pool Invites

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/admin_dashboard.html

Fetches and displays a list of invites for a given pool. Includes functionality to copy invite links and delete invites.

```javascript
function loadPoolInvites(poolId) {
  const container = document.getElementById("pool-invites-list");
  container.innerHTML = '<div class="loading-state"><sl-spinner></sl-spinner></div>';
  fetch(`/admin/api/cometnet/pools/${encodeURIComponent(poolId)}/invites`)
    .then(res => res.json())
    .then(invites => {
      if (!invites || invites.length === 0) {
        container.innerHTML = '<div class="empty-state"><sl-icon name="envelope"></sl-icon><p>No invites found for this pool</p></div>';
        return;
      }
      container.innerHTML = invites.map((invite) => {
        const link = `${window.location.origin}/invite/${invite.invite_code}`;
        const expires = invite.expires_at ? new Date(invite.expires_at * 1000).toLocaleString() : 'Never';
        const uses = `${invite.uses}/${invite.max_uses}`;
        return `
<div class="tracker-item" style="display: flex; justify-content: space-between; align-items: center;">
  <div style="font-family: monospace; font-weight: bold; font-size: 1.1em; overflow: hidden; text-overflow: ellipsis;">${invite.invite_code}</div> <div class="tracker-stats"> <span>Expires: ${expires}</span> <span>Uses: ${uses}</span> </div> 
</div> <div style="display: flex; gap: 5px; flex-shrink: 0;">
  <sl-button size="small" variant="neutral" outline onclick="copyInviteLink('${link}')"> <sl-icon slot="prefix" name="copy"></sl-icon> Copy </sl-button>
  <sl-button size="small" variant="danger" outline onclick="deletePoolInvite('${poolId}', '${invite.invite_code}')"> <sl-icon slot="prefix" name="trash"></sl-icon> </sl-button>
</div> 
</div> 
`; })
    .join("");
    })
    .catch(e => {
      console.error(e);
      container.innerHTML = '<div class="empty-state"><p>Error loading invites</p></div>';
    });
}
```

--------------------------------

### Configure CometNet for VPS/Server

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/quickstart.md

Enable CometNet and set FastAPI workers to 1 for a single instance on a VPS or server. Configure bootstrap nodes or manual peers as needed.

```env
COMETNET_ENABLED=True
FASTAPI_WORKERS=1

COMETNET_BOOTSTRAP_NODES='["wss://bootstrap.example.com:8765"]'
COMETNET_MANUAL_PEERS='["ws://friend-comet.example.com:8765"]'
```

--------------------------------

### Get Series Episode Stream Information (IMDB)

Source: https://context7.com/g0ldyy/comet/llms.txt

Fetches stream metadata for a series episode using an IMDB ID. Requires a base64 encoded configuration.

```bash
curl "http://localhost:8000/eyJ.../stream/series/tt0903747:1:1.json"
```

--------------------------------

### Build Comet Add-on Zip Only

Source: https://github.com/g0ldyy/comet/blob/main/kodi/README.md

Use 'make package' to build only the add-on zip file, excluding the repository. This is useful for quicker builds when only the add-on itself is needed.

```sh
cd kodi
make package
```

--------------------------------

### Get Series Episode Stream Information (Kitsu Anime)

Source: https://context7.com/g0ldyy/comet/llms.txt

Fetches stream metadata for an anime episode using a Kitsu ID. Requires a base64 encoded configuration.

```bash
curl "http://localhost:8000/eyJ.../stream/series/kitsu:44511:1:1.json"
```

--------------------------------

### Trigger Background Scraper Action

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/admin_dashboard.html

A generic function to trigger actions (start, stop, pause, resume) on the background scraper. It sends a POST request and handles success/error messages.

```javascript
async function triggerBackgroundScraperAction(action, successMessage) {
  try {
    const response = await fetch(
      `/admin/api/background-scraper/${action}`,
      {
        method: "POST",
      },
    );
    const data = await response.json().catch(() => ({}));
    if (!response.ok || data.success === false) {
      throw new Error(data.message || data.detail || "Request failed");
    }
    showToast(successMessage, "success");
    await loadBackgroundScraperData();
  } catch (error) {
    console.error(`Background scraper ${action} failed:`,
    error);
    showToast(
      `Background scraper ${action} failed: ${error.message}`,
      "danger",
    );
  }
}
```

--------------------------------

### Authenticate Configuration Page

Source: https://context7.com/g0ldyy/comet/llms.txt

Authenticate against CONFIGURE_PAGE_PASSWORD to set a signed session cookie. A successful authentication redirects to the configuration page.

```bash
curl -c cookies.txt -b cookies.txt \
  -X POST http://localhost:8000/configure/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "password=mysecretpassword&next=/configure"
```

--------------------------------

### Fetch Paired Kodi Configuration

Source: https://context7.com/g0ldyy/comet/llms.txt

Allows the Kodi add-on to retrieve the base64 config string using a previously generated pairing code.

```APIDOC
## GET /kodi/get_manifest/{code}

### Description
Called by the Kodi add-on to retrieve the base64 config string after user association. Consumes and deletes the pairing code on success.

### Method
GET

### Endpoint
/kodi/get_manifest/{code}

### Path Parameters
- **code** (string) - Required - The Kodi pairing code.

### Response
#### Success Response (200)
- **secret_string** (string) - The base64 encoded configuration string.
- **stremio_api_prefix** (string) - The prefix for Stremio API calls.

#### Error Response (404)
- **detail** (string) - "Manifest not ready or setup code expired"

### Response Example
```json
{
  "secret_string": "eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCJ9",
  "stremio_api_prefix": ""
}
```
```

--------------------------------

### GET /admin/api/connections

Source: https://context7.com/g0ldyy/comet/llms.txt

Lists all active proxied debrid stream connections, including real-time bandwidth metrics such as bytes transferred, current speed, peak speed, and average speed.

```APIDOC
## GET /admin/api/connections — Active Debrid Stream Connections

Lists all active proxied debrid stream connections with real-time bandwidth metrics (bytes transferred, current speed, peak speed, average speed).

### Method
GET

### Endpoint
/admin/api/connections

### Response
#### Success Response (200)
- **connections** (array) - A list of active debrid stream connections.
- **global_stats** (object) - Global statistics for all connections.

### Response Example
```json
{
  "connections": [
    {
      "id": "conn_abc",
      "ip": "1.2.3.4",
      "content": "Interstellar.2014.1080p.BluRay.mkv",
      "timestamp": 1717000000.0,
      "duration": 125.3,
      "bytes_transferred_formatted": "1.4 GB",
      "current_speed_formatted": "12.5 MB/s",
      "peak_speed_formatted": "18.3 MB/s"
    }
  ],
  "global_stats": {
    "total_bytes_alltime_formatted": "42.7 TB",
    "active_connections": 1,
    "peak_concurrent": 8
  }
}
```
```

--------------------------------

### Docker Compose for Private Network Deployment

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/docker.md

Configuration for deploying Comet in a private network setup. It uses container names, restart policies, and specific environment variables for private networking.

```yaml
services:
  comet:
    container_name: comet
    image: g0ldyy/comet
    restart: unless-stopped
    ports:
      - "8000:8000"
      - "8765:8765"
    environment:
      DATABASE_TYPE: postgresql
      DATABASE_URL: comet:comet@postgres:5432/comet
      COMETNET_ENABLED: "True"
      FASTAPI_WORKERS: "1"
      COMETNET_PRIVATE_NETWORK: "True"
      COMETNET_NETWORK_ID: my-private-network
      COMETNET_NETWORK_PASSWORD: ${COMETNET_NETWORK_PASSWORD}
    env_file:
      - .env
    volumes:
      - comet_data:/app/data
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    container_name: comet-postgres
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: comet
      POSTGRES_PASSWORD: comet
      POSTGRES_DB: comet
    volumes:
      - postgres_data:/var/lib/postgresql/
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U comet -d comet"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  comet_data:
  postgres_data:
```

--------------------------------

### Configure Manual Peers

Source: https://github.com/g0ldyy/comet/blob/main/docs/cometnet/cometnet.md

Provide a JSON array of trusted peers to always connect to. Format: '["ws://friend:8765"]'.

```env
COMETNET_MANUAL_PEERS='["ws://192.168.1.100:8765"]'
```

--------------------------------

### GET /admin

Source: https://context7.com/g0ldyy/comet/llms.txt

Provides access to the password-protected admin interface. It renders a login form, and upon successful authentication via POST /admin/login, it sets an `admin_session` cookie and redirects to /admin/dashboard.

```APIDOC
## GET /admin — Admin Dashboard Login

Password-protected admin interface. Renders a login form. On success (`POST /admin/login`) sets a signed `admin_session` cookie and redirects to `/admin/dashboard`.

### Request Example
```bash
# Login
curl -c admin_cookies.txt -X POST http://localhost:8000/admin/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "password=ADMIN_DASHBOARD_PASSWORD_value"
# 303 → /admin/dashboard

# Access dashboard (requires cookie)
curl -b admin_cookies.txt http://localhost:8000/admin/dashboard
```
```

--------------------------------

### POST /configure/login

Source: https://context7.com/g0ldyy/comet/llms.txt

Authenticates against CONFIGURE_PAGE_PASSWORD and sets a signed `configure_session` cookie. The cookie is valid for CONFIGURE_PAGE_SESSION_TTL seconds.

```APIDOC
## POST /configure/login — Configuration Page Authentication

Authenticates against `CONFIGURE_PAGE_PASSWORD` and sets a signed `configure_session` cookie valid for `CONFIGURE_PAGE_SESSION_TTL` seconds.

### Method
POST

### Endpoint
/configure/login

### Parameters
#### Request Body
- **password** (string) - Required - The password for authentication.
- **next** (string) - Optional - The URL to redirect to after successful authentication.

### Request Example
```bash
curl -c cookies.txt -b cookies.txt \
  -X POST http://localhost:8000/configure/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "password=mysecretpassword&next=/configure"
# 303 redirect to /configure on success
# Re-renders login page with error on failure
```
```

--------------------------------

### Get Debrid Services Data (JavaScript)

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

Retrieves the currently configured debrid services and their API keys from the DOM. It iterates through each '.debrid-service-entry' element and extracts the selected service and API key values.

```javascript
function getDebridServices() {
  const container = document.getElementById("debridServicesContainer");
  const entries = container.querySelectorAll(".debrid-service-entry");
  const services = [];
  entries.forEach(entry => {
    const service = entry.querySelector(".debrid-service-select").value;
    const apiKey = entry.querySelector(".debrid-api-key").value;
    if (service && apiKey) {
      services.push({ service, apiKey });
    }
  });
  return services;
}
```

--------------------------------

### Get Movie Stream Information

Source: https://context7.com/g0ldyy/comet/llms.txt

Fetches stream metadata for a movie. It looks up torrents, checks debrid availability, ranks torrents, and returns Stremio stream objects. Requires a base64 encoded configuration.

```bash
curl "http://localhost:8000/eyJkZWJyaWRTZXJ2aWNlIjoicmVhbGRlYnJpZCIsImRlYnJpZEFwaUtleSI6Ik1ZS0VZIn0/stream/movie/tt0816692.json"
# {
#   "streams": [
#     {
#       "name": "[RD⚡] Comet 1080P",
#       "description": "Interstellar (2014)\n🎥 H.264 | 🔊 DTS | 📦 14.2 GB | 🌱 1200 | 🔗 YTS",
#       "url": "http://localhost:8000/eyJ.../playback/abc123hash/0/5/n/n?torrent_name=...&name=Interstellar&media_id=tt0816692",
#       "behaviorHints": {"bingeGroup": "comet|realdebrid|abc123hash", "filename": "Interstellar.2014.1080p.BluRay.x264", "videoSize": 15258890240}
#     },
#     {
#       "name": "[🧲] Comet 720P",
#       "description": "...",
#       "infoHash": "def456hash",
#       "sources": ["tracker:https://..."]
#     }
#   ]
# }
```

--------------------------------

### Build Per-User Stream Configuration

Source: https://context7.com/g0ldyy/comet/llms.txt

Construct a JSON payload for per-user stream configuration, serialize it, and then base64-encode it. This encoded string is appended to Stremio URLs. This example shows how to configure debrid services, filtering, and result display options.

```python
import base64, json

# Build a ConfigModel payload
config = {
    # Debrid services (multi-service)
    "debridServices": [
        {"service": "realdebrid", "apiKey": "MY_RD_KEY"},
        {"service": "alldebrid",  "apiKey": "MY_AD_KEY"}
    ],
    "enableTorrent": False,      # also show direct magnet streams
    "cachedOnly": True,          # only show cached (instant) results
    "deduplicateStreams": True,  # one stream per torrent across services
    "sortCachedUncachedTogether": False,
    "scrapeDebridAccountTorrents": True,   # scan debrid account library
    "debridStreamProxyPassword": "supersecret",  # must match server setting

    # Filters
    "maxSize": 30.0,             # GB; 0 = no limit
    "maxResultsPerResolution": 3,  # 0 = no limit
    "removeTrash": True,

    # Result display fields
    "resultFormat": ["title", "video_info", "audio_info", "size", "seeders", "tracker"],

    # RTN settings (resolution/language/ranking)
    "resolutions": {"r2160p": True, "r1080p": True, "r720p": True, "r480p": False, "r360p": False, "unknown": False},
    "options": {"title_similarity": 0.85, "remove_all_trash": True, "remove_unknown_languages": False, "allow_english_in_languages": True},
    "languages": {"required": [], "exclude": ["fr", "de"], "preferred": ["en"]}
}

b64 = base64.b64encode(json.dumps(config).encode()).decode()
manifest_url = f"http://localhost:8000/{b64}/manifest.json"
stream_url   = f"http://localhost:8000/{b64}/stream/movie/tt0816692.json"
print(manifest_url)
```

--------------------------------

### Copy Manifest URL to Clipboard

Source: https://github.com/g0ldyy/comet/blob/main/comet/templates/index.html

Event listener for a button click that retrieves current settings, generates the manifest URL, and copies it to the user's clipboard. Provides visual feedback upon completion.

```javascript
copyLinkButton.addEventListener("click", () => {
  const settings = getSettings();
  const manifestUrl = getManifestUrl(settings, false);
  const textArea = document.createElement("textarea");
  textArea.value = manifestUrl;
  document.body.appendChild(textArea);
  textArea.focus();
  textArea.select();
  document.execCommand("copy");
  document.body.removeChild(textArea);
  console.log(`Copied manifest URL: ${manifestUrl}`);
  copyAlert.toast();
});
```