Self-Hosting

Deploy and run your own Vyla API instance locally or on your infrastructure

Overview

Vyla API is a self-hosted Node.js application that you run on your own infrastructure. It is designed for local/desktop deployment and does not provide any public hosted instances. The API server has no required external services besides SQLite for API key storage. It runs as a single process that can fork into multiple workers via the built-in cluster module, with an in-memory cache shared across workers through the primary process.

Vyla API is self-hosted only. There is no public hosted API available. You must deploy and run your own instance to access streaming features.

Requirements

• Node.js 18 or later
• SQLite (included automatically through better-sqlite3)
• A TMDB API key if you want title validation and metadata lookups

Environment variables

Create a .env file in the project root:

TOKEN_SECRET=a-random-string-at-least-32-characters-long

TMDB_API_KEY=
GA_MEASUREMENT_ID=
GA_API_SECRET=

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

Variable reference

Variable	Required	Description
TOKEN_SECRET	Yes	HMAC signing secret for session tokens. Must be at least 32 characters. Generate one with openssl rand -hex 32.
TMDB_API_KEY	No	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.

Database setup

The API uses SQLite through better-sqlite3. No external database service or connection string is required.

On startup, initAuth() calls ensureApiKeysTable() and ensurePublicKey(). These functions automatically create the database directory, initialize SQLite, create the api_keys table, and seed a default public key if one does not already exist.

The database is stored at:

data/api_keys.db

The table structure is:

CREATE TABLE IF NOT EXISTS api_keys (
    key TEXT PRIMARY KEY,
    type TEXT NOT NULL DEFAULT 'standard',
    rpm INTEGER NOT NULL DEFAULT 100,
    active INTEGER NOT NULL DEFAULT 1,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

Key types are:

• public
• standard
• partner

The seeded public key is:

public_api_key

with a default rate limit of:

10 requests per minute

To manually add API keys, insert rows directly into the SQLite database:

INSERT INTO api_keys (key, type, rpm, active)
VALUES ('your_api_key', 'standard', 100, 1);

Keys are cached in memory and refreshed from SQLite every 5 minutes. Disabling a key (active = 0) takes effect after the next refresh cycle.

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.

The stream-api repository is private. You need access to the GitLab repository to clone it. Contact the Vyla team for repository access if needed.

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. Requires a standard or partner API key.

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.

Desktop Application

For users who prefer a desktop application over running the Node.js server directly, Vyla provides a desktop version that includes the streaming API. The desktop application runs the same backend services but with a simplified user interface.

The desktop version includes:

• Built-in streaming API server
• Desktop player interface
• Automatic updates
• Simplified configuration

Contact the Vyla team for access to the desktop application if you prefer this approach over self-hosting the Node.js server.