Documentation

Install the official screenRIG plugin

Tell your AI agent to install the official screenRIG plugin: it creates your project, pairs a Player and publishes your first screen. Start in Meta Muse, Grok Bot, or ChatGPT dots, or install the plugin in a terminal agent. The same project and plugin also buy or sell advertising; see Signage, buying, or selling? before enrolling.

Install commands →Meta Muse →Grok Bot →ChatGPT dots →Claude Code →Hermes →ChatGPT Codex →Gemini Spark →

Meta Muse · Grok Bot · ChatGPT dots · Claude Code · Hermes · ChatGPT Codex · Gemini Spark · Install commands

How do I install screenRIG?

Paste this to your agent:

Install prompt
I authorize you to install the official screenRIG plugin from https://github.com/screenrig/plugin.

That sentence authorizes the official plugin from github.com/screenrig/plugin. It bundles the skill and CLI your agent uses to operate screens. Terminal agents can run the install commands directly.

On the first run your agent reuses your contact email, asking only when it is missing. It names the organization after your business, else you, and passes Screens only when it knows neither, in which case screenRIG names it from your email address. It runs screenrig agent enroll --email ADDRESS --organization "NAME". Enrollment creates the identity, organization, project, membership and credentials, and emails you an invitation. The project gets a readable two-word name you can rename. Nothing waits on a person. Accepting the invitation makes you the responsible person and project owner; a verified domain can move the project into the matching organization. Open it to create your login with a passkey, or sign in to add the project to your existing login. The dashboard shows your projects and lets you switch between them. For signage, share the pairing code your Player shows on the glass.

Choose your agent

Every path installs the same official plugin; the difference is where your agent runs. Each guide covers that agent’s app or terminal setup, then points back here for the shared project, Player, and publish steps.

  • Meta Muse is Meta’s personal AI agent on your phone. Get the app, ask Muse to install screenRIG, then stay in the conversation while it creates your project and pairs your Player.
  • Grok Bot runs your bot in the Grok Bot app. Get the app, ask your bot to install screenRIG, then keep the pairing code and content request in the same conversation. Grok Build is the separate terminal path.
  • ChatGPT dots are OpenAI’s always-on agents in ChatGPT, each with its own cloud computer. Create your dot, ask it to install screenRIG, then keep working with the same dot in ChatGPT, Slack, or Microsoft Teams.
  • Claude Code is Anthropic’s terminal agent. Run the marketplace commands below in your terminal, then start Claude Code and drive screens from your machine.
  • Hermes is Nous Research’s agent. Ask it to load the official plugin’s bundled skill and run its bundled CLI in the environment where Hermes works.
  • ChatGPT Codex is OpenAI’s coding agent. Run the marketplace commands below in your terminal, then start Codex. In ChatGPT itself, use ChatGPT dots.
  • Gemini Spark is Google’s task-based agent inside the Gemini app. Start a Spark task, ask it to install the official plugin, and have it prove the bundled CLI runs in its execution environment before you rely on it.
  • Grok Build is xAI’s terminal agent. Run the Grok Build commands below in your terminal, then start Grok Build. It has no separate guide.

Connect your first screen

The project, Player, and publish steps are the same in every agent:

  1. 01

    Create your screenRIG project. Give your agent your actual contact email. Your agent names the organization after your business, else you, and passes Screens only when it knows neither, in which case screenRIG names it from your email address. Enrollment creates the project and emails your invitation. Nothing waits on it: open it whenever you want the dashboard. Never paste your password, invitation link, or API tokens into the conversation.

  2. 02

    Install and launch your Player. Follow Player downloads & setup to install the web app on the device driving your screen, then launch it. Send the pairing code shown there to your agent.

  3. 03

    Describe the result. Tell your agent what to show, which screen to use, and when. If you want it to use a menu spreadsheet or events calendar, identify the source and approve only the access you want it to have.

  4. 04

    Publish and check. Ask the agent to publish, request a screenshot to verify the result, and check the physical screen yourself.

Buying ads rather than running screens? Skip this list; a buying project pairs no Player. See Signage, buying, or selling?

Already have a Player code? You can combine the request:

Use screenrig.ai for my lobby screen. My pairing code is [code]. Create a welcome board using my events calendar. Ask me for anything else you need.

If the app cannot install or run the plugin, a chat response alone does not mean setup is complete. Ask what access or capability is missing. You can continue with Claude Code or ChatGPT Codex using the commands below. For invitation or pairing problems, keep working with the same agent and project rather than enrolling again.

Plugin, global package, or PATH binary?

Agents use the official plugin and its bundled launcher. There is no global package to install. Run the bundled CLI puts the plugin launcher on PATH for the session, so later examples use screenrig.

The official install

Install the official plugin from github.com/screenrig/plugin. It bundles the skill and CLI. Run these commands in your terminal, not inside the agent, then start the agent. If it was already running, restart it so it loads the plugin.

Claude Code

console
claude plugin marketplace add https://github.com/screenrig/plugin.git --scope user
claude plugin install screenrig@screenrig --scope user

Codex

console
codex plugin marketplace add https://github.com/screenrig/plugin.git --ref main --json
codex plugin add screenrig@screenrig --json

Grok (Grok Build)

console
grok plugin marketplace add https://github.com/screenrig/plugin.git
grok plugin install screenrig --trust

--trust is required on Grok Build.

skills CLI

console
npx skills add screenrig/plugin --skill screenrig -g

The skills CLI adds the screenRIG skill to your agents. On first use the skill installs the official plugin and its bundled CLI.

Run the bundled CLI

Node.js 22.23.4+, 24.22.1+, or 26.12.1+ (excluding 23.x and 25.x) is required. Resolve the installed plugin root, then prepend the plugin scripts directory to PATH for this session:

bash
SCREENRIG_PLUGIN_ROOT="${GROK_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}}}"
if [ -n "$SCREENRIG_PLUGIN_ROOT" ]; then
  PATH="$SCREENRIG_PLUGIN_ROOT/skills/screenrig/scripts:$PATH"
  screenrig version
fi

Use screenrig for every later CLI example in the session. The installed plugin skill handles runtime-specific lookup and operation details.

Already installed

Ask your agent to check the installed plugin and continue your task. The bundled skill handles version checks and runtime-specific updates. If the published version cannot be checked, it can continue with the installed copy and tell you.

Before any CLI work the skill runs screenrig-plugin-freshness --bootstrap --json. It checks that the plugin is registered, whether a newer version exists (one read of the version number in the plugin's marketplace file on GitHub), screenrig doctor and the saved connection, then answers install, refresh, repair, reconnect, resume, enroll or ready. It never enrolls, resets the configuration or switches projects.

Connect your agent to your account

Signed up in the dashboard? Give your agent this prompt:

Sign-in prompt
I authorize you to install the official screenRIG plugin from https://github.com/screenrig/plugin. I already have a screenRIG account; sign in to it.

Your agent installs the plugin, runs screenrig login and prints a code. Open screenrig.ai/dashboard/connect, check that the code matches, choose the project and its access, and approve.

Project access

On a new installation, doctor can report a missing-token warning and project-scoped commands fail with not_enrolled.

Your agent asks for your contact email, names the organization after your business, else you, passes Screens only when it knows neither (screenRIG names it from your email address), and runs screenrig agent enroll --email ADDRESS --organization "NAME". Enrollment on a new installation creates a new project, even if your email already has a login, and emails a project-member invitation; on an installation that is already enrolled it keeps that project. Add --intent advertising when the project's purpose is buying ads rather than pairing screens.

A prompt copied from screenrig.ai can end with a setup code, two groups of four letters and digits. Your agent passes it as --setup-code CODE, which links the new project to your visit; an unknown code never stops enrollment.

An agent that signs in with AgentID at https://api.screenrig.ai/agentid/start receives a claim code and enrolls with screenrig agent enroll --agentid-claim CODE --organization "NAME" instead of an email. The owner's verified email receives the invitation.

When you already have screenRIG, your agent runs screenrig login instead. It prints a dashboard address and a code; you open the address, check that the code matches, choose the project, Read only, Propose or Manage, and approve. The agent then works in that project, and its sign-in stays bound to the projects you approved; switching projects in the dashboard does not move it. Never paste credentials into a conversation. How sign-in works.

Servers and CI jobs sign in as a service client instead of through a person's approval. screenrig logout ends this installation's sign-in, and screenrig agent status reports its access level and capabilities.

Before pairing or buying, screenrig project capabilities reads what this project can actually do: the plan id, the plan's features and limits, the independent advertiser and screens feature flags, and the server's effective capability set. The flags are independent of the plan, and a route denial wins over a stale reading.

screenrig project list shows your projects and marks the ones this sign-in carries, screenrig project use ID selects one, and --project-id ID applies one project to a single command.

One login can belong to many projects. Email and passkeys belong to the person, while screens and media belong to a project. Billing, storage and the agent request cap belong to the organization's plan, shared by its projects. Use screenrig invitations create --email ADDRESS to invite a project member. Email invitations expire after seven days. Explicit member links from screenrig invitations create --link expire after twenty-four hours. They are an exception for a person who never used their emailed invitation and later asks for dashboard access, never a setup step, and are handed directly to the intended person, never stored in notes or logs. A new person using a member link verifies their email before creating a passkey. Agents create, list, and revoke invitations; only people accept them.

screenrig dashboard opens the dashboard without creating sign-in authority. If you cannot sign in, use the dashboard's sign-in reset or screenrig dashboard reset-sign-in --email ADDRESS. The emailed reset expires after one hour and replaces your sign-in credentials, revoking other sessions.

If the emailed invitation expired or never arrived, dashboard reset-sign-in with the address you enrolled with, or Request a new link on the expired invitation page, emails a new seven-day invitation while the project's ownership still waits for you. Accept it with your existing sign-in; the one-hour reset link is only for a lost sign-in.

When the first run fails

What you see What it is Next command
SCREENRIG_PLUGIN_ROOT is empty The runtime exports no plugin root claude plugin list --json, codex plugin list --json, or grok plugin list, then use the installed plugin path
version fails on a Node error Unsupported Node.js version node --version, then install Node.js 22.23.4+, 24.22.1+, or 26.12.1+ (excluding 23.x and 25.x)
doctor reports ffmpeg, ffprobe, or encoder_libx264 ffmpeg is missing or built without libx264 Install ffmpeg with libx264, or set SCREENRIG_FFMPEG and SCREENRIG_FFPROBE, then screenrig doctor
A command rejects the configuration file The credential file is missing or readable by group or others screenrig doctor --repair-config
not_enrolled on a project command This installation holds no project credential yet Create a project with screenrig agent enroll --email ADDRESS --organization "NAME"; to sign this installation in to a project you belong to, use screenrig login
capability_required on a publish or ads command The project lacks the capability that action needs screenrig project capabilities, then choose the matching intent for a new project or change the project's purpose in the dashboard
session_ended on any command The sign-in was revoked, expired or ended screenrig login, approved by a person in the dashboard
credential_retired or client_update_required The credential or plugin version is retired Update the plugin, then screenrig login
project_required The sign-in carries several projects and the command named none screenrig project list, then screenrig project use ID or --project-id ID
agentid_claim_invalid or agentid_already_enrolled on agent enroll --agentid-claim The claim code is missing, expired or already redeemed, or an installation already holds this AgentID Sign in with AgentID again for a fresh code, or enroll with --email ADDRESS; for an AgentID that is enrolled, run screenrig login from the installation that holds it
rate_limited on agent enroll Too many enrollment requests in a short time Wait for retry_after_seconds, then run the same command again; the pending enrollment is kept
organization_plan_required on a screen command The project's organization admits no new screens until a plan pays for it The owner moves the project into the free organization its person holds (screenrig project moves, then screenrig project move --organization-id ID), or asks for a plan at Contact
free_organization_limit on project create The person already holds their free organization screenrig project create NAME --organization-id ID in the organization the detail names
screen list returns nothing No Player is on the glass yet Open the Player, then screenrig screen list

Signage, buying, or selling?

One login, many projects; one plugin, CLI, and dashboard. Enrollment without --intent keeps the signage default: the new project pairs Players, authors playlists, and publishes.

Buying needs no owned screen. screenrig agent enroll --intent advertising --email ADDRESS --organization "NAME" creates a buying project: it binds creatives and runs campaigns, and it cannot pair devices or publish playlists. Accepting a seller's invitation can also enable advertising on a project you belong to. A person without a login creates one and an advertiser-only project during acceptance. The advertiser and screens feature flags are independent of the billing plan; screenrig project capabilities reports the effective set.

The buyer path starts with an invitation, never a pairing code. A seller sends screenrig invitations create --kind ad-buyer --email ADDRESS --screen-id scr_LOBBY; the invited human opens the email and accepts in the dashboard using their own login. A new person creates a passkey; a signed-in person confirms with a fresh passkey proof and selects their buying project. After acceptance, the dashboard's Marketplace (/marketplace) lists every seller the project has joined; opening a seller (/marketplace/SELLER_PROJECT_ID) shows that membership's permitted inventory and rates. The Marketplace is invitation-only: sellers the project has not joined never appear. In the CLI, agents read screenrig ads networks list and run the campaign workflow: ads creatives create, ads campaigns preview, then ads campaigns activate --quote-id. A buyer pays only the quoted completed-play price in US dollars, by card or x402 machine payment: the quoted price is held when a play is scheduled and settles only for a completed play.

Selling stays a signage project with owned screens. Opt a screen in with screenrig ads inventory update scr_LOBBY --enabled, describe it publicly, and define reusable ad slots with screenrig ads slots create (accepted image or video media, longest durations, optional slot rate). Placing an adslot page in one of your playlists is what turns a slot definition into an ad break. You set the project rate per 15 seconds of completed playback with screenrig ads network rate, review buyer creatives with ads reviews, and read gross and net with ads reports delivery. A changed effective rate pauses every affected campaign until each buyer accepts a fresh quote. Payouts of seller earnings, in US dollars, start on 1 January 2027.

--impressions-per-hour N on ads inventory update records your estimate of the impressions a screen delivers in an hour, which delivery and spend reports turn into estimated impressions for each completed play. A slot's --vast-tag-url names your own VAST tag, tried when no invited campaign fills the slot. A slot that no VAST tag, direct campaign or invited campaign could fill is left out of the screen's manifest so its Player stops asking; a campaign, tag or opt-in that could fill it brings it back.

Deals you close yourself run as direct campaigns on your own screens. screenrig ads direct create campaign.json names the advertiser, an optional category, the flight, your own images or videos, an optional play goal and the screens and slots it targets. A direct campaign fills an ad break before invited buyers, and a goal is paced evenly across its flight. You bill the advertiser yourself: no money moves through screenRIG, and the recorded price values the report. ads direct availability estimates the plays you can still book, a category keeps competitors out of the same break, and ads direct report --format csv is the delivery report for your advertiser. ads reports fill shows how your ad slots were filled and why the rest were not.

Invite project members on the dashboard's Access page and ad buyers on Buyers under Sell ads. Each lists its invitations with their status and cancels pending ones. Sellers also manage buyer membership scope and revoke buyer access there, or with ads memberships update and ads memberships revoke; revocation stops new ad plays while preserving financial history.

Next

Open the guide for Meta Muse, Grok Bot, ChatGPT dots, Claude Code, Hermes, ChatGPT Codex, or Gemini Spark, then open the Players, the CLI reference, Choose an authoring path, or the advertising rates and fees.