# Self-host Stream API

<p class="page-description">Deploy the optional Stream API when your clients need an HTTP/SSE layer.</p>

## Overview

Stream API is a **self-hosted Node.js** application that you run on infrastructure you control. It does not provide a public hosted instance. The service runs as a Node.js process, uses in-memory caching, and can fork workers through Node's built-in `cluster` module. No database is required by the service itself.

:::callout-warning
Stream API is self-hosted only. There is no public Vyla streaming endpoint. You only need it when your architecture requires an HTTP/SSE layer; Node.js applications can use [Vyla SDK](/sdk) directly.
:::

## Requirements

- Node.js 18 or later
- A TMDB API key if you want title validation and metadata lookups

## Environment variables

Create a `.env` file in the project root:

```bash
TMDB_API_KEY=
PORT=7860
WORKER_COUNT=1
ENABLE_DEBUG_ROUTE=false
PROXY_STREAMS=false
PROXY_URL=

GA_MEASUREMENT_ID=
GA_API_SECRET=
```

<div class="card">
  <div class="card-title">Variable reference</div>
  <div class="card-body">

| Variable | Required | Description |
| --- | --- | --- |
| `TMDB_API_KEY` | Yes | Enables TMDB-based ID validation, metadata lookups, and anime detection. Some sources will not work without it. |
| `GA_MEASUREMENT_ID` / `GA_API_SECRET` | No | Enables Google Analytics event reporting. Leave blank to disable. |
| `PORT` | No | Port the server listens on. Defaults to `7860`. |
| `WORKER_COUNT` | No | Number of cluster workers to fork. Defaults to `1` locally. |
| `ENABLE_DEBUG_ROUTE` | No | Set to `true` to enable `/api/debug/:id`. Keep this `false` in production - it exposes upstream request/response headers and raw source output. |
| `PROXY_STREAMS` | No | Set to `true` to route stream playback through your own server's `/api` proxy endpoint instead of direct URLs. |
| `PROXY_URL` | No | An external proxy base URL to use instead of the built-in `/api` proxy. Only used if `PROXY_STREAMS` is enabled. |

  </div>
</div>

## Installing and running

```bash
git clone https://gitlab.com/vyla-entertainment/stream-api
cd stream-api
npm install
node server.js
```

The server listens on:

```
http://localhost:7860
```

Visit `/health` to confirm it is running and check which sources are currently reachable from your host.

## Running with multiple workers

Setting `WORKER_COUNT` above `1` forks additional worker processes via `cluster`.

The primary process holds a shared in-memory cache (capped at 1500 entries, pruned every 30 seconds) and relays cache reads/writes between workers over IPC, allowing cached stream results to be shared rather than duplicated.

```bash
WORKER_COUNT=4
node server.js
```

Each worker independently loads source modules and handles outbound requests. Only shared cache operations and concurrency limits are coordinated through the primary process.

## Network considerations

Several sources are documented in `config.js` as blocked on datacenter IPs. This commonly affects cloud hosting providers and VPS environments.

If a source's `getStream` consistently returns nothing from your server but works from a residential connection, the cause is usually upstream blocking based on IP reputation. For the best experience, run Vyla API on a residential connection or use a residential proxy.

When running on a local desktop environment, you should have minimal issues with source availability since you're using a residential IP address.

## Reverse proxy / TLS

The server runs over plain HTTP. For public deployments, place it behind a reverse proxy such as Caddy, Nginx, or Cloudflare Tunnel to terminate TLS and forward requests to the configured `PORT`.

CORS is already configured at the application layer with:

```
Access-Control-Allow-Origin: *
```

No additional CORS configuration is required on the proxy.

## Verifying your deployment

Run these checks in order:

1. `GET /health`

   Confirms the process is running and reports per-source reachability from your host.

2. `GET /api/test/155?source=vidrock`

   Runs a real source resolution using a known TMDB movie ID and returns whether the source succeeded.

3. `GET /api/debug/155?source=vidrock`

   Only available when `ENABLE_DEBUG_ROUTE=true`.

   Returns request traces, headers, and raw candidate URLs for debugging source failures.

:::callout-warning
Leave `ENABLE_DEBUG_ROUTE` disabled on public deployments. The debug route exposes upstream request information and raw stream URLs, which can leak internal details.
:::