Self-host Stream API

Deploy the optional Stream API when your clients need an HTTP/SSE layer.

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.

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 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:

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

# Optional telemetry configuration
GA_MEASUREMENT_ID=
GA_API_SECRET=

Variable reference

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.

Installing and running

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.

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.

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