The Agent

scorbit-feed is a small command-line program, included in the @scorbit/feed package, that holds a feed open and serves it on your own computer. It is the easiest way to drive an OBS overlay or a local display, because the page it serves never handles a credential.

Run it as npx @scorbit/feed, never npx scorbit-feed: without a local install, npx resolves the bare name to a different, unrelated package. Once @scorbit/feed is installed in your project, the scorbit-feed command is also available to your npm run scripts.

Commands

# List what your key covers (uuid, game name, venue), as JSON.
SCORBIT_API_KEY=sb_live_... npx @scorbit/feed machines

# Open a feed on specific machines; the agent deletes it when it exits.
SCORBIT_API_KEY=sb_live_... npx @scorbit/feed --machines <uuid>,<uuid>

# ...or on everything your key covers (a venue-scoped key's feed follows its venues).
SCORBIT_API_KEY=sb_live_... npx @scorbit/feed

# Attach to a feed opened elsewhere; the agent never deletes it.
SCORBIT_FEED_TOKEN=sbf_... npx @scorbit/feed --feed-id f_...

# Show every command and option.
npx @scorbit/feed --help

Credentials come only from the SCORBIT_API_KEY and SCORBIT_FEED_TOKEN environment variables, never from arguments, and are never logged or served.

Options

Option	Default	Effect
--machines <uuid,...>	the key's whole scope	Open the feed on these machines only, in this order
--feed-id <id>		Attach to an existing feed instead of opening one (needs SCORBIT_FEED_TOKEN)
--transport sdk\|sse	sdk	Connection type; use sse where WebSockets are blocked
--port <n>	8787	Port to serve on
--host <addr>	127.0.0.1	Address to listen on. Anything else exposes the feed to your network
--static <dir>		Also serve your overlay or display files from this folder
--cors-origin <origin>		Allow pages from another origin to read the feed; repeatable
--allow-file-origin	off	Allow any page that sends Origin: null, such as a page opened from disk (file://), to read /state and /events. See the warning below
--base-url <url>	https://api.scorbit.io	Scorbit API address

Routes

Route	Returns
GET /state	{ status, updated_at, machines }: the latest state of every machine. Machines that leave a following feed drop out
GET /events	Server-Sent Events: status events carry { status }; state events carry the same body as /state; machines events carry { added, removed, machines } when the set changes, just before the state that carries it. The current status and state are sent as soon as you connect
GET /healthz	200 while the feed is running and 503 once it has ended, with body { ok, status, agent: "scorbit-feed" }
/ and other paths	Your --static files, if set

The machines in /state have the same shape as the machines in an update message.

Which Pages Can Read the Agent

Browsers are allowed from http://localhost and http://127.0.0.1 on any port, and from each --cors-origin. Any other origin is refused with 403.

• Served by the agent (--static): works with no extra options. This is how the Quick Start runs.
• Opened from disk (file://): prefer serving the page with --static instead. If you must open it from disk, start the agent with --allow-file-origin; the page may then read only /state and /events.
• Served by your own web server: allow that server's origin with --cors-origin <origin>.

--allow-file-origin lets websites read your feed

A page opened from disk identifies itself as Origin: null, but so does a sandboxed iframe on any website. With --allow-file-origin on, a website you visit in a browser on the same computer could read your live machine and player data from the agent while it runs. Use --static instead whenever you can, and turn the flag on only while you need it.

The starter overlay reads the agent at http://127.0.0.1:8787 unless you point it elsewhere with ?agent=<http(s) url>.

Stopping

On Ctrl-C (or SIGTERM) the agent stops the feed, deletes it if the agent opened it, and exits. A feed you attached to with --feed-id is left running.

Running It Unattended

The agent must keep running for your display to update. When its feed ends for any reason other than Ctrl-C, for example after being stopped from Scorbit Console, the agent logs the reason and exits with status 1.

It exits with status 1 for every other failure too, for example an invalid key or a feed it could not open, and with status 2 for a mistake in its command line.

For a display that runs all day, start the agent with your operating system's service manager or a process manager set to restart it when it exits, with a delay of at least 30 seconds between restarts (for example RestartSec=30 in systemd, or --restart-delay in pm2). Without the delay, a problem that stops the agent at once, such as a revoked key, turns into a stream of failed requests that quickly hits the rate limits. In create mode each restart opens a fresh feed; with --feed-id, a restart re-attaches to the same feed, which may already have ended. If the agent keeps exiting, the logged reason tells you why. See Lifecycle and Troubleshooting.