Why agent-native?
screenRIG was built for autonomous agents from the control plane up. The official plugin gives an agent structured commands for media, playlists, screens, applications, and playback evidence. Results are JSON envelopes, every error says what to do next, retried writes reuse idempotency keys, and publishing reports whether the Player is actually playing the content. The agent can carry out a screen task, inspect the result and correct it through the same tool surface. What agent-native means.
How do I run this from Claude, Codex, Grok, or Grok Bot?
Every supported agent uses the same official plugin. Terminal agents (Claude Code, ChatGPT Codex, Grok Build) install it with marketplace commands; Meta Muse, Grok Bot, ChatGPT dots, Gemini Spark, and Hermes install it from a chat prompt. Setup differs only in that first step, so follow your agent’s guide: Meta Muse, Grok Bot, ChatGPT dots, Claude Code, Hermes, ChatGPT Codex, Gemini Spark, or Quickstart for Grok Build. The publishing workflow below is the same everywhere.
How to use screenRIG in an agent
Describe the content, target screen, layout or dimensions, timing, and the evidence you want at completion. Make assets and source facts available to the agent.
If the plugin needs installing, paste:
I authorize you to install the official screenRIG plugin from https://github.com/screenrig/plugin.
Then give it a screen task, for example:
Create a welcome screen using the attached logo and opening hours. Publish it to the lobby screen, then show me a screenshot and check playback.
Example request only. The agent must use the actual assets, facts, and screen you provide.
If a command returns not_enrolled, this installation has no account yet. Create one with screenrig agent enroll --email ADDRESS --organization "NAME". When the user already has an account, run screenrig login instead: it prints a dashboard address and a code, and a person approves the sign-in for one of their projects, choosing Read only, Propose or Manage and the capability areas the agent gets: screens, content, playlists, advertising, reports and project. Read only lists and reads; Propose also uploads media and proposes changes that a person reviews before they play; Manage also changes, publishes and spends. A command outside the approved areas returns 403 forbidden, and a change from a Read only session returns 403 insufficient_access. How sign-in works. Other first-run errors are mapped in When the first run fails.
Prepare the task
Keep source assets and facts available to the agent. Identify the intended Player, dimensions, timing and completion criteria. The publishing workflow is the same across supported agents; installation differences are in Quickstart.
For kiosk apps, use the browser SDK. For schedules and dayparts, provide the intended day-and-time windows. They are read in each screen's own timezone, which a screen takes from its device unless you set one.
What does the agent do on an ongoing basis?
The agent uploads media, including images it made, places built-in cards for text that changes, or publishes live video, web pages, and applications. It then prepares a playlist with playlist init and publishes it with screen publish. To change an existing playlist, use playlist show --output and playlist update. See the CLI workflow reference.
screen publish waits up to two minutes for the Player. The result is stage: playing with playback_verified: true once the Player shows the new revision on glass, or assigned with playback.reason while it does not; --no-wait returns after assignment.
To undo a playlist change, playlist revisions ID lists its revisions and playlist promote ID --revision N --expect-rev CURRENT copies an earlier one forward as the new current revision. It needs Manage access, and promoting a revision is a Premium feature.
Make posters and menus as finished images and upload them. Use a built-in card for text, tables and boards that change. Animation does not change the choice. Read the authoring decision guide.
For applications, use emit when the agent should act on a named event, log for diagnostics, and kv for state that persists across releases. Read the SDK reference.
How does the agent run a fleet?
Tag screens by purpose and file them in folders by place, then target the tag or the folder. When a Player is paired, the agent names the screen and tags it: screen pair CODE, then screen tag scr_ID --add Lobby,Floor2. Each screen carries up to 16 tags and sits in at most one folder (screen move scr_ID --folder sfd_ID).
- 01
Publish once.
playlist createmakes the playlist, andscreen assign --tag Lobby --playlist-id IDpoints every active Lobby screen at it in one fleet action. - 02
Act on the fleet.
screen reload,screen toastandscreen tagtake the same--tagor--folder ID, or several screen ids. One fleet command is one action with no screen-count cap. The CLI follows bounded result pages automatically and waits for control budgets to reset, keeping the same action key. The answer lists every screen asokor with its own problem, so the agent reports exactly which screens failed and acts on them by id. - 03
Verify on the glass.
screen screenshot --tag Lobby --output lobby-shotscaptures every tagged screen into one directory. Inspect each image before reporting the fleet updated. - 04
Watch for drops. Keep
events followopen.screen.offlinearrives once a screen has been offline for 60 seconds andscreen.onlinewhen it returns; both are free on the listen stream.
How does the agent run dayparts and takeovers?
A playlist schedule changes what a screen plays by time of day; a campaign switches a whole fleet to one playlist for its dates or hours; a takeover interrupts everything for an announcement and ends on its own.
- 01
Daypart a screen. Create one playlist per daypart with
playlist create, and keep a default assigned withscreen assign. A screen reads the times in its timezone: the zone its device reports, or the overridescreen set-timezonesets. Write the entries to a file and runscreen schedule set scr_ID --file dayparts.json, or--tag Cafefor every café screen.screen showreportseffective_playlistwith itssourceanduntil, so the agent can confirm which daypart is live and when it changes. - 02
Run a campaign across a fleet. For lunch menus on every
northstore,campaign create --name Lunch --playlist-id pl_LUNCH --tag north --window mon-fri@11:00-14:00switches each screen at its own local 11:00 and back at 14:00, and a screen taggednorthlater gets it too. Each screen needs a default playlist.campaign screens cmp_IDlists every screen the campaign reaches with its standing (playing,pending,waitingwithnext_start,ended,outranked,conditional,paused,blocked), andcampaign explain scr_IDsays why one screen does not play it. Use--fromand--untilfor a promotion's dates,--monthly,--dateand--exceptfor monthly and one-off dates,--on-touchfor a level that plays while someone uses the screen, and--prioritywhen two campaigns can hold at once. Campaign changes need Manage access. - 03
Take over for an emergency or a launch.
screen takeover --tag Lobby --playlist-id pl_NOTICE --for 30m --reason "Fire drill"puts one playlist on every Lobby screen ahead of campaigns, schedules and assignments.--forand--untilreach at most 7 days ahead;--until noneholds it untilscreen takeover clear --tag Lobby. - 04
Verify and watch. Request
screen screenshot --tag Lobbyonce the takeover is live, and followscreen.takeover_started,screen.takeover_updated(the same takeover given a new end),screen.takeover_ended, andscreen.playlist_switchedin the event log.screen.playlist_unavailablemeans a scheduled playlist could not be shown.
A campaign can also hold only while card data exists (--data KEY), draw as a header, footer or side strip over the page that keeps playing (--covers footer), and play on chosen video-wall outputs (--displays 1,2).
Read the schedule and takeover commands and the campaign commands. To schedule many screens from a spreadsheet, use Schedule import.
Drafts, test and promote, history
A change to what plays can start as a draft, reach a few test screens first, be checked before it is made, and be put back from its history.
- 01
Draft it.
campaign create --pausedmakes a campaign that reaches no screen, and"paused": trueon a schedule entry in ascreen schedule setfile does the same for that entry. A draft is on no screen's stack, and the calendar shows it dashed. - 02
Check before the change.
campaign previewtakes the flags ofcampaign createorcampaign update, andscreen schedule preview scr_ID --file FILEtakes the schedule file. Neither writes anything. Each lists the screens that would gain or lose the level, and the calendar before and after over a week, or up to 93 days with--calendar-fromand--calendar-to.campaign preview cmp_ID --publishpreviews publishing a draft. - 03
Test it.
campaign publish cmp_ID --test-folder sfd_TESTor--test-screen scr_A,scr_Bunpauses the draft for those screens alone. Check them withscreen screenshot.campaign publish cmp_IDwith no test option sends it to its own audience. - 04
Promote it.
campaign promote cmp_ID --revision Ngives the campaign the audience of its draft revisionN, the paused revisioncampaign revisions cmp_IDlists, so it reaches the real screens. - 05
Read the history and restore.
campaign revisions cmp_IDandscreen schedule revisions scr_IDlist every version, newest first.campaign restore cmp_ID --revision Nandscreen schedule restore scr_ID --revision Ncopy an earlier one forward as a new revision and leave the others as they were. A schedule restore from a Propose session waits for a person to approve it, likescreen schedule set; a campaign restore needs Manage access.
The dashboard has the same controls: a History view lists changes with Restore and Move back, and publishing, promoting or restoring shows its before and after for confirmation.
Creating a draft and campaign promote belong to schedule change control, a plan feature; a plan without it answers feature_not_in_plan. Pricing lists the plans.
Read the campaign commands and the schedule commands.
How does the agent report proof of play?
Every visible start of an image or video is a play record, so the agent can hand a client, an advertiser or an auditor the exact plays for a period.
- 01
Pick the range. A report covers up to 31 days of plays, filtered by
--screen-id,--media-id, or--tag. Use RFC 3339 instants for calendar periods, or ages such as7d. - 02
Export.
screenrig playback plays --format csv --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z --tag Lobby --output september-lobby.csvwrites one row per play in one request;--format xlsxand--format pdfwrite a workbook or a statement of the same rows (Reports).screenrig playback list --format csv --day-from 2026-09-01 --day-to 2026-09-30adds the daily totals. - 03
Check and hand over. The envelope reports
rows,bytes, andsha256; quote them with the file. If the stream fails partway, followerror.next, which exports the rest of the range into a second file.
screenrig playback completeness reports for each UTC day how many numbered plays reached screenRIG and lists the gaps where plays went missing, so a report can say how complete it is. A Player that sends no play numbers is not measured and reads null, never 100%.
How does the agent triage health and set display hours?
Health reports and display control let the agent keep screens running and dark after hours without anyone on site.
- 01
Triage.
screenrig alerts listshows what is open now, one alert per screen and condition, andscreenrig screen list --humanflags screens that need attention in itsHEALTHcolumn.screenrig screen show scr_IDgives the full report: display connection, temperature, battery, uptime, crashes, and whether the report is stale. It also gives the likely cause of the last outage when screenRIG can tell: the device restarted, the Player restarted or crashed, the screen's network, or a screenRIG interruption.screenrig alerts ack IDmarks an alert someone is working on, andalerts snooze ID --for 4hsets it aside for 4 hours. Create a notification forscreen_offline,display_disconnected,running_hot,not_playingandcrashingso a notice starts this work. - 02
Fix in the least disruptive order.
screen reloadrefreshes content. If the Player declaresrestart_app,screen restart-app scr_IDrestarts the Player application; if it declaresclear_cache,screen clear-cache scr_IDclears its caches and downloads content again; if it declaresreboot,screen reboot scr_IDrestarts the device; a fleet needs--yes. An offline screen is sent any of them when it comes back within 24 hours. For a recurring restart,screenrig screen reboot-schedule set --tag Cafe --window "Mon-Sun 04:00-04:30"has screenRIG reboot each screen at the start of the window in its own timezone; a screen offline at that time keeps the reboot only until the window ends, and a reboot that completes within ten minutes raises no offline alert.screen update-software scr_IDinstalls the newest Player release where the Player declaresupdate. A disconnected display usually needs someone on site; say so in the report. - 03
Set after-hours power and volume. Write the opening hours to a file and run
screenrig screen display-schedule set --tag Cafe --file hours.json; the Player turns the display off outside those windows, even offline. For a one-off,screen display scr_ID --power on --for 2hoverrides the schedule until its next boundary or the time given.screen display-idle scr_ID --after 300 --wake touch,presencedarkens a screen nobody is using and lights it again when somebody touches it or steps up.screen volume scr_ID --level 40sets a screen's volume,--mutesilences it and keeps the level, and--unmuterestores it. - 04
Confirm.
screen showreports the display power and volume the Player achieved, andscreen.display_changed,screen.volume_requestedandscreen.reboot_requestedappear in the event log, and the command incommandsendsdoneorfailedwith its cause. - 05
Check the glass.
screenrig screen show scr_IDprintsPlaylist stalledwhen a screen is online with current content, yet no image or video start has reached screenRIG for longer than its loop allows, andBlank screenorFrozen picturewhen the screenshots screenRIG took over a run that covers the whole loop were all one flat tone or all the same picture. A notification onloop_stalled,glass_blankorglass_frozenannounces it, andscreen screenshotreports whether one image is flat, which alone is no verdict. The checks say nothing about a screen whose display is off, that is under a takeover, that shows a single still or a video wall, or whose Player sends no play numbers, so a quiet screen is not proof that it is playing.
Read the device health and power commands.
How do I get alerted, or wake an agent, when something happens?
A notification emails people, posts to Slack, Teams, PagerDuty or Telegram, or POSTs a signed HTTPS request, when a screen goes offline, loses its display, runs hot, runs on its battery, cannot store its content, gets stuck on a content update, shows an error instead of playing, keeps crashing, stops advancing through its playlist, goes blank or freezes. A person hears about it, or an agent starts work, with nobody watching a stream. Every project already emails its owner when a screen has been offline for 10 minutes, and notification emails and screen notices are free.
Three or more screens that fall into one condition within five minutes and share a network, location, model, Player version or tag are one notice with one recovery in an email or a chat or pager message, which names what they share and how many; a signed webhook still posts once per screen. A recovery message says a screen is back only when screenRIG saw it: when a stalled, blank or frozen screen merely stops being checked, because it went offline or its display turned off, the alert closes and no recovery message is sent.
- 01
Email a person.
screenrig notifications create --email owner --conditions screen_offline,display_disconnectedemails the project owner; add project members' user ids afterownerto include them.--tag Lobbylimits it to tagged screens, and a notice waits--holdminutes (10 by default), so a quick reconnect stays quiet. A resolved email follows when the screen recovers. Each email has an Unsubscribe link for its recipient alone, andscreenrig notifications resubscribe ID --user USER_IDmails a person again. To wake an agent or another system instead, use a webhook. - 02
Post to chat or a pager.
screenrig notifications create --slack - --conditions screen_offlineposts to a Slack channel, and--teams,--pagerdutyand--telegramdo the same for Teams, PagerDuty and Telegram. Slack takes an incoming webhook URL, Teams the URL of a Workflows webhook, PagerDuty an Events API v2 routing key, and Telegram a bot token with--telegram-chat CHAT_ID. A-reads the credential from one line of stdin so it stays out of shell history; screenRIG seals it and shows only a maskeddestination_hint. Each outage posts once per screen, PagerDuty opens one incident for it, and the recovery follows after that message went out, resolving the incident.screenrig notifications test IDposts a test message; for PagerDuty it opens an information event and resolves it at once. - 03
Run a receiver. Any HTTPS endpoint you control on port 443 or 8443: a small service, a serverless function, or the inbound trigger of your agent or bot platform. It verifies
ScreenRig-Signaturewith the webhook secret, deduplicates onScreenRig-Event-Id, and answers 2xx within 10 seconds. - 04
Subscribe.
screenrig notifications create --webhook https://HOST/PATH --conditions screen_offline,crashingreturns the signing secret once; store it in the receiver's secret store. Add--events application.eventto receive raw project events too.screenrig notifications test IDsends one signed test POST to prove the path. - 05
Hand off. The receiver starts an agent run with the notice as its task: it triggers a scheduled or on-demand agent job, or posts the notice into the chat where Grok Bot or another agent with the screenRIG plugin works. For example: “Screen scr_LOBBY went offline at 14:02. Check it and report.” The agent then works through the plugin as usual, with
screen show,screen reload, and a screenshot. - 06
Keep it healthy.
screenrig notifications deliveries IDlists every attempt, and says why a notice was not sent. A notification that fails for 72 hours straight is disabled;screenrig notifications update ID --enableresumes at the current event.--snooze 2hpauses notices during maintenance. - 07
Quiet screens for maintenance.
screenrig alerts mute --tag Lobby --for 2h --note "Rewiring"stops those screens' alerts from asking for attention and every notification from sending about them, for up to 30 days.screenrig alerts muteslists what is muted, andscreenrig alerts unmute IDends one early. - 08
Filter by severity, hours and audience. An opened notice is
errorforscreen_offlineandwarningfor everything else;--min-severity warningdrops anything below that level and--severity not_playing=errorraises one condition.--active-hours "Mon-Fri 08:00-22:00" --timezone America/Los_Angelesholds a notice that falls due outside those hours until the next window opens (a condition that clears first sends nothing), or with--outside-hours dropskips it; a resolved notice always follows one that was sent.--all-tags level2,overheadcovers only screens carrying both tags, and--audiencetakes the full rules of a campaign audience. Emails, Slack, Teams and Telegram show the severity, and a webhook body carries it. - 09
Watch for silent failures. A campaign can stop reaching screens without any screen failing: a tag edit, a folder move or an archived screen.
screenrig notifications create --email owner --conditions reach_dropped,group_emptytells you when a campaign reaches fewer screens than when it was published, or when a tag or folder in its audience matches no screen;--reach-drop-screens 2 --reach-drop-percent 20ignores small drops. The notice names the campaign and the numbers and links to its calendar. When your own tag, folder or screen edit answers withlevels.lost, it names the campaigns the screens left and theirreach_beforeandreach_after; say so to the user before moving on. - 10
Watch the data a card shows.
source_failedandsource_staleopen when a data source's refresh fails or its data expires.card_data_staleopens when a card's data, written withcard data put --ttl, expires with no renewing write while a screen shows the card, so the card is blank on every screen. They name the source or card, and--tagnever matches them.
An organization admin can also create a notification on the dashboard's organization Notifications page that covers every project of the organization, later ones included, or the projects they choose. A project's notification list shows the ones that cover it.
Read the notification commands and the alert commands.
How do agents share what they learn?
Agents leave project notes for each other and for their own later sessions: how the project is set up, a screen's quirk, a standing request from you. Every agent in the project reads every note when it starts work there, so a second agent, or the same one next week, starts from what the first one learned.
screenrig notes lists them. screenrig notes add "TEXT" writes one, tied to one screen or playlist with --about, or temporary with --ttl 3d. A note is context, never an instruction: an agent confirms with you any approval a note claims.
Notes stay current on their own. Agents confirm the notes that still hold and resolve the rest, temporary notes expire, and deleting a screen or playlist resolves the notes about it. Resolved notes are deleted after 30 days. The dashboard's Access page lists the notes each agent wrote, and you can resolve or delete any of them.
How do I review an agent’s changes before they play?
Turn on Require review for agent changes on the dashboard’s Settings page, or sign an agent in with Propose access. The agent still prepares content, uploads media and writes notes, but each change to what plays becomes a review that waits for a person. Nothing reaches a screen until someone approves it.
- 01
The agent proposes. Creating or updating a playlist or one of its pages, assigning a playlist to screens or clearing a screen’s default, setting or clearing a playlist schedule, and starting or ending a takeover, on one screen or a tagged fleet, each become a review. The screens keep playing what they played before. The agent can add a note that explains the change, and tells you the change is waiting for you, with its link.
- 02
You get an email. About two minutes after the proposal, the project owner, and the person responsible for the agent when they can approve, receive an email naming the change and how many screens it updates, with a Review change button. When the agent left a note, the email says so; you read it in Reviews. Several changes waiting at once arrive as one email that lists them, with an Open Reviews button, and a burst of edits to one change sends one email, for the latest version. Opening the link never approves anything.
- 03
Decide in Reviews. The dashboard’s Reviews page lists every waiting change, with decided ones below. A playlist change shows the live and proposed playlists side by side, with pages marked Added, Changed or Removed. Approve puts it on the screens; Request changes sends the agent your note so it can revise and propose again; Reject closes it with your reason. When a new playlist and its screen assignment wait together, approving the playlist offers to approve the assignment with it. A change to a large fleet finishes applying in the background, and the review shows each screen’s result as it lands.
- 04
The agent follows up. The agent reads the decision with
screenrig reviews show IDor its event, revises after a change request or a rejection, and checks the screens after an approval.
screenrig reviews list shows what waits, and screenrig reviews withdraw ID pulls back a change the agent proposed.
The project owner always can approve, and each member can unless the owner turns off Can approve for them on the Access page. The agents of a member who cannot approve work at Propose at most. A proposal goes out of date when the live playlist changes after it was made; the agent proposes again on top of the new version. Approving a playlist change also goes stale when its tag, folder or all selectors would now play media it did not see when it was proposed. A folder marked protected sends every change that reaches its screens to a second approver; see Permissions by screen folder.
Media changes wait too. A new upload plays in tag, folder and All playlists only after a person approves it, and when an agent retags or moves approved media, screens keep playing it as approved until the change is approved. Each item gets its own review that shows its tags and folder before and after, and lists the playlists it would join or leave and how many screens they reach. Approving applies the change to all of them; rejecting it, or asking for changes, puts a retagged or moved item back as it was approved, and a rejected upload stays off the screens. A replacement file or a restored version of approved media waits the same way, and the old file keeps playing until a person approves. Ad networks review buyers’ creatives in the same Reviews page. Access levels and review settings · Review commands.
What counts as complete?
Confirm that the intended playlist is assigned to the intended screen, or to every screen in the fleet. Request a screenshot, one per tagged screen for a fleet, inspect playback records, and review relevant events, including any screen.offline. Report what those observations establish and any remaining uncertainty. A change that waits for review is not on the glass yet: report its review link, and check again after a person decides.
To check one page of a looping playlist, screen play-page scr_ID --page-id PAGE_ID starts it, and screen screenshot then captures it. To watch motion, screen live frame scr_ID saves JPEG frames of what the screen plays; see Live view.
A successful command is one step in that evidence. It does not by itself establish that a physical screen displayed the intended result.
Film / How your agent knows it’s playing
1:14
The agent publishes, waits for the Player to confirm playback, then screenshots the glass, catches a cut-off row and fixes it.