Edge Cache Runner

The Edge Cache Runner turns a signageOS player (BrightSign, or any Node-capable player) into a LAN caching reverse-proxy. Other devices on the same network fetch their assets through that player: each asset crosses the WAN only once, is stored on the player's local storage, and is then served locally to every other device that asks for it.

Use it to cut WAN/uplink bandwidth on sites with many screens, speed up playback of shared media, and keep content available during brief origin or internet outages.

Feature entitlement: runners · Plan: 👑 Pro Device Plan or higher

How do I get Runners onto my devices?

See the Runners overview for assigning, configuring, and activating a Runner in Box.

How devices use the cache

Point a device at the cache by prefixing the original asset URL with the caching player's address:

http://<edge-player-ip>:8888/proxy/<URL-encoded origin URL>

For example, to fetch https://cdn.example.com/video.mp4 through a caching player at 192.168.1.50:

http://192.168.1.50:8888/proxy/https%3A%2F%2Fcdn.example.com%2Fvideo.mp4

A compatibility form without URL-encoding is also accepted (.../proxy/https://cdn.example.com/video.mp4, as long as it contains no spaces, #, or literal %).

Only GET and HEAD requests are proxied — any other method returns 405. Every response includes an X-Cache header so you can see how it was served:

X-Cache	Meaning
HIT	Served from the local cache, no WAN traffic
MISS	Fetched from the origin and stored for next time
REVALIDATED	Re-checked with the origin (still valid), no re-download
STALE	Origin/WAN failed — a still-usable cached copy was served
BYPASS	Not cacheable (see below) — streamed straight through

CORS headers are added to every response, so browser- and PWA-based applets can read the content directly.

Caching behaviour

• The runner honours the origin's Cache-Control and Expires headers by default. Responses marked no-store or private are never stored (they are streamed through as BYPASS). If you set respectOriginCacheControl to false, the runner caches every response by its own lifetimes instead — including no-store and private ones, which are then served to every device on the LAN. max-age=0/no-cache responses are stored but re-validated on every request.
• When the origin sends no caching headers, a configurable default lifetime applies. Origin-provided lifetimes are clamped to a configurable minimum/maximum.
• On an origin or internet failure, the runner serves a bounded-stale copy (serve-stale-on-error) so playback continues through short outages.
• Storage is managed with an LRU eviction policy within a disk budget and a free-space floor. Writes are atomic and the cache index is crash-safe: cached content survives a device reboot with no re-download.
• Simultaneous requests for the same missing asset produce a single origin download that is streamed to all waiters at once.

Authentication, tokens & protected content

Many signage assets sit behind tokens or authentication. The Edge Cache Runner handles this predictably:

• Auth headers are forwarded verbatim. Authorization, Cookie, and custom headers such as X-Api-Key are passed to the origin unchanged (including on revalidation). Hop-by-hop headers like Proxy-Authorization are stripped.
• Signed-URL tokens in the query string are part of the cache key — different tokens are cached as different entries. If your tokens rotate on otherwise-identical content, list those parameter names in ignoreQueryParams so the cache keys past them.
• By default the cache is a shared, single-tenant LAN cache: the same URL is served to every device on the LAN regardless of which token requested it. This is the right model when all your screens belong to one tenant. For genuinely personalised content, have the origin mark it Cache-Control: private (or no-store) — it will then never be stored or shared, as long as respectOriginCacheControl stays true.
• To cache the same URL separately per token/tenant, add authorization to the varyHeaders setting. Each distinct Authorization value then gets its own cache entry, with no cross-token sharing.
• Failed-auth responses (401/403) are relayed to the requesting device and never cached.

Running actions from Box

The runner's Set panel in Box exposes an action selector:

Action	Effect
none	No action (default)
purge-cache	Clears the entire cache immediately

Select purge-cache and press Save to empty the cache on the device — for example after publishing new content that reuses existing URLs. All other settings (port, admin token, cache size, …) live in the runner's Configuration, not the Set panel.

Telemetry & monitoring

The runner reports live telemetry to Box, visible in the Runner section of the device detail view (and via the Runners REST API):

Field	Meaning
state	running, starting, or degraded
version	Runner version
lastError	Last startup/runtime error, if any
entries	Number of cached objects
usedBytes	Cache size on disk
hits / misses	Requests served from cache vs. fetched from origin
bytesServed / bytesFetched	Bytes delivered to devices vs. downloaded from origins
degraded	1 when storage is degraded and the runner is passing traffic through

You can build alert rules on these values — for example, alerting when state is not running or when the hit-rate drops.

Admin dashboard

The runner also serves a status dashboard on the same port (cache size, hit-rate, cached-files and recent-requests tables). Set the adminToken configuration value to require a password for the dashboard and to enable the data/admin API. If left unset, the dashboard runs in a read-only, low-security mode (query strings are redacted and mutating actions are disabled) — setting a token is recommended in production.

Configuration reference

Every setting is optional; sensible defaults apply when a field is left empty. The most useful ones:

Setting	Default	Purpose
port	8888	LAN listener port
cacheDir	auto	Cache location; auto probes persistent storage (/storage/sd, /storage/ssd, /storage/usb1)
maxCacheSizeBytes	5 GiB	Cache disk budget
minFreeSpaceBytes	500 MiB	Free-space floor before eviction
respectOriginCacheControl	true	Honour origin Cache-Control/Expires; when false, private/no-store responses are cached and shared too
serveStaleOnError	true	Serve a bounded-stale copy on origin failure
maxStaleSeconds	7 days	How long a stale copy may be served
varyHeaders	[]	Header names added to the cache key (e.g. ["authorization"] for per-token isolation)
ignoreQueryParams	[]	Query parameters removed before cache keying (rotating signed tokens)
originAllowlist	[] (any public origin)	Restrict which origins may be cached
allowPrivateOrigins	false	Allow LAN/loopback origins (off by default as an SSRF guard)
adminToken	unset	Password for the dashboard and admin API

The runner's Configuration screen in Box lists the full set of parameters (timeouts, redirect limits, connection limits, TTL clamps, and more) with inline descriptions.

Availability

The Edge Cache Runner runs in the signageOS browser runtime and is validated on BrightSign. It has zero third-party runtime dependencies.