# How to deploy headless digital signage that your agent runs > Canonical HTML: https://screenrig.ai/guides/deploy-headless-digital-signage To deploy headless digital signage, connect your AI agent or your code to screenRIG, install the Player on each device with one fleet link so it joins your project on its own, and let the agent publish, watch and repair screens through the CLI, the API or the MCP server. Nobody opens a dashboard. Updated November 12, 2026. This guide walks through a ten-screen rollout, from an empty project to a fleet that tells you when something breaks. This is a real, read-only session on our own test screen, an onn 4K Streaming Device on a test rack, run on 9 November 2026 through the screenRIG MCP server. Times are Vancouver time. > **You:** Check the ONN Test Rack. Is it healthy, what is it playing, and did anything go wrong this week? > > **Agent:** It's online on Wi-Fi at -54 dBm, with no crashes in the last 24 hours, and its content is current: the ONN Test Rack — Demo playlist. The Player reports the TV's display as off right now, so nothing is on the glass. It was offline from Thursday 04:58 to Saturday 14:48, about 58 hours, and screenRIG puts that down to a device restart. That offline alert, and a stalled-loop alert on Tuesday from 10:51 to 10:58, are both resolved. Its Player can clear its cache and restart the app, but it doesn't declare reboot, so a hard hang on that device still needs someone at the TV. The last screenshot it stored is from 2 November. The rest of this guide is the rollout itself: from an empty project to a fleet that reports like this. ## What "headless" means here 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](https://screenrig.ai/headless-digital-signage.md) explains the model, and [the API page](https://screenrig.ai/developers.md) covers every interface. ## Step 1: Connect the agent, or a service client for code 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](https://screenrig.ai/docs/start.md) 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](https://screenrig.ai/docs/mcp.md) 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: ```bash 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](https://screenrig.ai/docs/service-clients.md) covers sign-in with a key or a secret. ## Step 2: Pick a player per screen 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](https://screenrig.ai/digital-signage/windows.md) 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](https://screenrig.ai/guides/digital-signage-player.md) compares them, and [Downloads](https://screenrig.ai/downloads.md) lists every device. ## Step 3: Provision with a fleet link, not pairing codes 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. ```bash 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](https://screenrig.ai/docs/players.md#fleet-links) has every device manager's setting. ## Step 4: Give each screen its time and its hours Schedules run in each screen's own timezone, so set it, then tell the screens when to be on: ```bash 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](https://screenrig.ai/guides/hdmi-cec-digital-signage.md). On every plan, a reboot schedule restarts devices in a quiet window, such as `"Mon-Sun 04:00-04:30"`. ## Step 5: Publish, and check that it is playing 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: ```bash 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. ## Step 6: Get told when a screen needs you Every project starts with one email to its owner when a screen has been offline for 10 minutes. Add the conditions you care about: ```bash 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. ## Step 7: Recover without a site visit 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](https://screenrig.ai/docs/cli/device.md#device) lists every device command and the Players that support it. ## A deployment checklist - 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 ## Frequently asked questions ### 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](https://screenrig.ai/pricing.md) for what the paid plans add. ## Sources - [screenrig.ai/docs/start](https://screenrig.ai/docs/start) - [screenrig.ai/docs/players](https://screenrig.ai/docs/players) - [screenrig.ai/docs/cli](https://screenrig.ai/docs/cli) - [screenrig.ai/docs/service-clients](https://screenrig.ai/docs/service-clients) ## Related - [Headless Digital Signage (API-First Screens)](https://screenrig.ai/headless-digital-signage.md): Headless digital signage: a CI pipeline updates a TV through the API with curl, with no dashboard open and no one watching. - [Digital Signage REST API, Webhooks and SDK](https://screenrig.ai/developers.md): Use the digital signage REST API for screens, playlists, media and schedules. OpenAPI docs, curl examples, webhooks, CLI, SDK and MCP tools. - [Automated Digital Signage That Runs Itself](https://screenrig.ai/digital-signage/automation.md): Automated digital signage: screens switch by time, weather, data and events, alerts take over on their own, and you hear when a screen needs you. - [Digital Signage Player: How to Choose One](https://screenrig.ai/guides/digital-signage-player.md): A digital signage player is the device that plays content on a screen. Compare Pi, BrightSign, sticks and PCs; the screenRIG Player is free. - [Supported Players and Setup](https://screenrig.ai/docs/players.md): Install the screenRIG Player on your screen, pair it with your agent, and compare content types, streams and device controls by platform. ## More guides - [TV Dashboard: Show Power BI, Tableau, Grafana](https://screenrig.ai/guides/dashboard-on-tv.md): Put a dashboard on a TV two ways: your AI agent draws the numbers big, or it plays your Power BI, Tableau, Grafana or sign-in dashboard on the screen. - [Control a TV with Meta Muse](https://screenrig.ai/guides/control-tv-with-muse.md): Meta Muse can run digital signage from your phone. Add the screenRIG connector, pair a TV with the code on its screen and ask Muse for what to show. - [Control a TV with Claude and Claude Code](https://screenrig.ai/guides/digital-signage-with-claude-code.md): Claude can run digital signage from Claude Code or the Claude app. Install the official screenRIG plugin, pair a TV and say what should be on it. - [Control a TV with Hermes Agent](https://screenrig.ai/guides/control-tv-with-hermes.md): Hermes Agent from Nous Research can run digital signage. Load the screenRIG skill, pair a TV with the code on its screen and ask for what to show. - [All guides](https://screenrig.ai/guides.md): Put a sheet, slides, a dashboard, a website or a camera on a TV by asking your AI agent. Each guide shows what to say and what to expect. [Start free](https://screenrig.ai/docs/start.md). screenRIG is free.