API Reference

Overlay Server

HTTP server that hosts overlay pages, static assets, and the WebSocket upgrade endpoint.

Overview

The overlay server runs inside the VMSC main process and serves overlay HTML pages, user media, and compiled front-end bundles. It also handles the WebSocket upgrade for real-time communication (see WebSocket Protocol).

Setting Value
Base URL http://localhost:7890
Default Port 7890
Protocol HTTP/1.1 (HTTPS available through tunnel)

Endpoints

GET /status

Health check endpoint. Returns the server's running state and the port it is listening on.

Response:

{
  "running": true,
  "port": 7890
}

Returns HTTP 200 when the server is healthy. Use this to verify the overlay server is reachable before opening overlay pages.

GET /overlay/:overlayId

Serves the full overlay HTML page for a given overlay. The server injects several global variables into the page before sending it to the client:

  • __VMSC_OVERLAY_ID__ — The overlay's UUID
  • __VMSC_PORT__ — The server port for WebSocket connection
  • __VMSC_TOKEN__ — A per-session authentication token
Parameter Location Description
overlayId URL path UUID of the overlay to render.

Dev mode: Loads the overlay HTML inline from the Vite dev server with hot module replacement enabled.

Production: Serves the compiled overlay.html from the build output directory with rewritten asset paths pointing to /overlay-assets/.

Returns HTTP 404 if the overlay ID does not match any configured overlay.

GET /assets/*

Serves user-uploaded media files (images, audio, video) from the userData/assets/ directory.

  • Automatic MIME type detection based on file extension
  • Path traversal protection — requests containing .. are rejected
  • Responses include a Cache-Control header with a 5-minute max-age

Returns HTTP 404 if the file does not exist, or HTTP 403 if the path is invalid.

GET /overlay-assets/*

Serves compiled JavaScript and CSS bundles from the out/renderer/ build output directory. These are the overlay client application files generated by the Vite build process.

This endpoint is only used in production mode. In development, assets are served directly by the Vite dev server.

Security

The overlay server applies several layers of protection to prevent unauthorized access and abuse.

Measure Details
CORS Restricted to localhost origins only. Cross-origin requests from other hosts are rejected.
Path Traversal All file-serving endpoints reject paths containing .. or other traversal sequences.
Auth Tokens WebSocket connections require a valid per-session token injected into the overlay HTML at serve time.
Content Sniffing All responses include X-Content-Type-Options: nosniff to prevent MIME sniffing attacks.
Rate Limiting Maximum of 10 connections per IP address. Excess connections are dropped.
Message Size WebSocket messages are capped at 512 KB. Oversized messages close the connection.
Local Network Exposure

By default, the overlay server binds to localhost and is not accessible from other devices on your network. If you need remote access, use the built-in tunnel system rather than exposing the port directly.