How to deploy headless digital signage that your agent runs

In a headless setup the control plane is an API, not a web page. Your agent, a script or a CI job makes the same calls a person would make in the dashboard, through the CLI, the REST API or the remote MCP server. The Player on each screen downloads what it is told to play, plays it from local storage, and reports back: what it is showing, its health, and which controls the device supports. The dashboard is still there for a person who wants it; nothing depends on it being open. Headless digital signage explains the model, and the API page covers every interface.

For an AI agent, paste one sentence to it and it installs the official screenRIG plugin, which bundles the skill and the screenrig CLI. On its first run it enrolls: it creates your organization and project and emails you an invitation. Quickstart has the sentence and the install commands for each agent.

An MCP client such as Claude, ChatGPT or Grok can connect to the remote MCP server instead: a person approves it in the dashboard and chooses Read only, Propose or Manage for it. Read only is enough for an agent that only watches, as in the session above. The plugin adds the steps that run on your machine, such as converting media and packing apps. Connect an MCP client has the server address and sign-in.

For a script, a CI job or your own service, create a service client with only the access it needs:

screenrig service-client create --name "rollout-pipeline" --access manage

A Read only client suits a monitoring job, and a Propose client's changes wait for a person to review them. Service clients covers sign-in with a key or a secret.

Choose devices that start on their own and that you can recover remotely. A Raspberry Pi or Linux PC on a kiosk install, a BrightSign player, a Windows PC or a managed Android device can all reboot on command; sticks and TV apps are cheaper but cannot. How to choose a digital signage player compares them, and Downloads lists every device.

A pairing code is fine for one screen. For ten, a fleet link is one Player URL that turns every device that opens it into its own screen in your project, with the link's tags, fields and playlist, and no code to read out.

screenrig fleet-links create --name "Kitsilano counters" --tag Kitsilano --tag Counter --playlist-id pl_MENU --max-screens 6 --expires-at 2026-11-30T23:59:59Z

The answer carries the URL. It is a credential that creates screens, so give it only to the device setup, never to a page or a chat. Then put it where the device will find it:

• Raspberry Pi and Linux. Run the installer as a kiosk with the link: curl -fsSL https://screenrig.ai/linux/install.sh | sh -s -- --kiosk --fleet-link URL. The device then boots straight into the Player, joins the project, and comes back by itself after a power cut.
• Android, Google TV and Amazon Signage Stick. Set the fleet_link key in the app's managed configuration in your device manager (package ai.screenrig.player).
• A factory-reset Android 10 or later device with a camera. Scan the link's Android device-owner QR code from the Welcome screen. The managed Player installs itself as the device's home app, full screen, with no device manager.
• Mac, Apple TV, iPhone and iPad. Set fleet_link in your MDM's managed app configuration.
• ChromeOS. Put the link in the kiosk app's URL in the Google Admin console.

--max-screens and --expires-at stop a leaked link from creating screens forever; the screens it already made keep playing. A device that is powerwashed or reinstalled comes back as the same screen once its old identity has been silent for ten minutes. The Player guide has every device manager's setting.

Schedules run in each screen's own timezone, so set it, then tell the screens when to be on:

screenrig screen set-timezone scr_KITS_COUNTER_1 --timezone America/Vancouver
screenrig screen display-schedule set --tag Window --file store-hours.json

The display schedule runs on the player, so a window goes dark at close even if the store's internet is down. Players that support it switch the TV itself over HDMI-CEC, DDC/CI or the backlight; the rest black out the picture. See HDMI-CEC for digital signage. On every plan, a reboot schedule restarts devices in a quiet window, such as "Mon-Sun 04:00-04:30".

An agent publishes from a sentence. From code, screen publish creates a playlist from a prepared file, assigns it, and waits until the Player reports it is showing it:

screenrig screen publish scr_KITS_COUNTER_1 menu.json
screenrig screen screenshot --tag Kitsilano --output shots/

An assignment is not proof of playback, so the publish waits for the Player, and a screenshot shows what is on the glass. Fleet changes go by tag or folder, and a fleet action is one request however many screens it reaches. A write can carry a revision check (--expect-rev), so two writers cannot silently overwrite each other.

Every project starts with one email to its owner when a screen has been offline for 10 minutes. Add the conditions you care about:

screenrig notifications create --email owner --conditions screen_offline,display_disconnected,not_playing,glass_blank,glass_frozen --tag Kitsilano

Notifications also watch for a device running hot, full storage, a content update that is stuck, a Player that keeps crashing and a playlist that has stopped moving. Email and signed webhooks come with every plan; routing to Slack, Teams, PagerDuty or Telegram comes with Plus. For an agent that reacts on its own, screenrig events follow streams the project's events, and screen events are free on the listen stream.

Each Player reports its health every fifteen minutes and at once when its display connection or power changes: uptime, memory, temperature where the device has it, network and crashes. screen show returns it with the screen's host capabilities, so the agent knows what a screen can do before it tries.

When a screen fails, the agent works from the cheapest fix up, and only uses what that Player declares:

1. Look. screen show reports the screen's last outage and, once a health report decides it, a likely cause: a device restart, an app crash, the network or screenRIG. A screenshot shows what is on the glass.
2. Reload. screen reload refreshes content without touching the device.
3. Restart the app or clear the cache. screen restart-app restarts the Player; screen clear-cache drops downloaded content, keeps the pairing, and downloads it again.
4. Reboot. screen reboot restarts the device on Players that support it. Sent to an offline screen, it waits, queued for up to 24 hours, and runs when the screen comes back. A reboot you asked for raises no offline alert while the device restarts.
5. Swap the hardware. If a device dies, pair the replacement and run screen replace: the new device takes over the old screen's name, tags, timezone, playlist, schedules and history.

The CLI reference lists every device command and the Players that support it.

• Agent connected, or a service client with the least access it needs
• Players chosen for remote reboot where a site visit is expensive
• One fleet link per store or group, with tags, a playlist, a screen cap and an expiry
• Each screen's timezone set
• Display schedule for screens that should be dark out of hours
• First publish verified with a screenshot from every screen
• Notifications for offline, disconnected display, not playing and blank or frozen picture
• A named person who receives the alerts

Do I need the dashboard at all?

No. Everything in this guide works from the agent, the CLI or the API. The dashboard is one more client, useful when a person wants to look.

Can I deploy without reading out pairing codes?

Yes. A fleet link enrolls every device that opens it, from a device manager, a Linux installer flag or an Android QR code.

What happens when the internet goes down at a store?

Native Players keep playing what they downloaded, and display schedules keep running on the device. You get an offline notice once the screen has been offline for the hold you set.

How much does a rollout cost?

screenRIG is free, with unlimited screens on Standard. See pricing for what the paid plans add.

• screenrig.ai/docs/start
• screenrig.ai/docs/players
• screenrig.ai/docs/cli
• screenrig.ai/docs/service-clients