Skip to main content
Stremio Web is a client-side single-page application (SPA). Once built, it is a directory of static files that can be served by any HTTP server. This page covers the main self-hosting options and recommendations.

​
Choosing an approach

ApproachWhen to use
DockerYou want a ready-to-run container with no additional setup
Static file serverYou already have an HTTP server or CDN and want to serve the build/ directory directly
See Docker deployment for the container-based approach. The rest of this page focuses on serving the static files yourself.

​
Serving the build directory

After building from source, the build/ directory is self-contained. Serve it with any HTTP server that can:
  • Serve static files
  • Fall back to index.html for unknown paths (required for SPA routing)

​
nginx

The following configuration serves the SPA and sets the recommended caching headers: 
server {
    listen 443 ssl;
    server_name stremio.example.com;

    ssl_certificate     /etc/ssl/certs/stremio.example.com.crt;
    ssl_certificate_key /etc/ssl/private/stremio.example.com.key;

    root /var/www/stremio-web/build;
    index index.html;

    # Hashed assets — safe to cache for a long time
    location ~* ^/[0-9a-f]{40}/ {
        expires 30d;
        add_header Cache-Control "public, max-age=2629744, immutable";
    }

    # index.html — short TTL so updates are picked up quickly
    location = /index.html {
        expires 2h;
        add_header Cache-Control "public, max-age=7200";
    }

    # Everything else (images, favicons, manifest)
    location / {
        try_files $uri $uri/ /index.html;
        expires 1d;
        add_header Cache-Control "public, max-age=86400";
    }
}
The try_files ... /index.html directive is required. Without it, navigating to a deep URL directly returns a 404 instead of loading the app.

​
HTTP caching recommendations

Stremio Web uses content-addressed asset paths (/<commit-hash>/scripts/main.js). You can take advantage of this with aggressive caching:
ResourceRecommended max-ageRationale
index.html2 hours (7200 s)Entry point must stay fresh so clients get new deploys
Hashed assets (/<hash>/...)1 month (2629744 s)Path changes with every deploy; safe to cache indefinitely
manifest.json, images, favicons1 dayInfrequently updated static assets
These values match what the built-in Docker server (http_server.js) applies.

​
HTTPS requirement

HTTPS is required. Stremio Web will not function correctly over plain HTTP because:
  • PWA installation and service workers only work on secure origins
  • stremio-core-web uses SharedArrayBuffer, which requires Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers (enforced on secure contexts)
If you need a certificate, Let’s Encrypt provides free TLS certificates.

​
Required security headers

To enable SharedArrayBuffer support, add these headers to responses serving index.html: 
add_header Cross-Origin-Opener-Policy "same-origin";
add_header Cross-Origin-Embedder-Policy "require-corp";

​
PWA installation

Stremio Web ships with a manifest.json and a service worker generated by Workbox. When served over HTTPS, browsers will offer to install it as a Progressive Web App. The service worker:
  • Caches the app shell and assets for offline use
  • Uses clientsClaim: true and skipWaiting: true, so a new version activates as soon as it is available
  • Caches files up to 20 MB in size
To disable the service worker (for example, in a controlled internal environment where you manage caching externally), set SERVICE_WORKER_DISABLED=true at build time:
pnpm run build --env SERVICE_WORKER_DISABLED=true

​
Connecting to Stremio Core

The in-browser app connects to Stremio Core (the streaming server) to handle torrent streaming, transcoding, and local add-on communication.
  • By default, the app attempts to connect to a locally running Stremio desktop application that exposes the Core API.
  • If you are self-hosting without a desktop app, users can point the app at any compatible Stremio Core endpoint via Settings → Advanced → Streaming server URL.
  • The Core and the web app must be on compatible versions. Check the @stremio/stremio-core-web dependency version in package.json for the bundled Core version.
The web app bundles stremio-core-web as a WebAssembly module, so basic functionality (add-on browsing, metadata) works without a separate server. A running Stremio Core is only required for actual video streaming.

Build docs developers (and LLMs) love

Get started for freeTalk to us