> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vyla.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  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.
</Warning>

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

```bash theme={null}
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=
```

<Card title="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.                                |
</Card>

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

```sql theme={null}
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:

```sql theme={null}
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

```bash theme={null}
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.

<Note>
  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.
</Note>

## 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 theme={null}
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.

<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.
</Warning>

## 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.