# Install the official screenRIG plugin

> Canonical HTML: https://screenrig.ai/docs/start/

Start in Meta Muse, Grok Bot, or ChatGPT dots, or install the plugin in a terminal agent. Then create a project, pair a Player, and publish your first screen. The same project and plugin also buy or sell advertising; see [Signage, buying, or selling?](https://screenrig.ai/docs/start.md#signage-buying-or-selling) before enrolling.

[Meta Muse](https://screenrig.ai/docs/start/muse/) · [Grok Bot](https://screenrig.ai/docs/start/grok-bot/) · [ChatGPT dots](https://screenrig.ai/docs/start/dots/) · [Claude Code](https://screenrig.ai/docs/start/claude-code/) · [Hermes](https://screenrig.ai/docs/start/hermes/) · [ChatGPT Codex](https://screenrig.ai/docs/start/chatgpt/) · [Gemini Spark](https://screenrig.ai/docs/start/gemini-spark/) · [Install commands](https://screenrig.ai/docs/start.md#official)

<a id="start"></a>

## How do I install screenRIG?

Paste this to your agent:

```text
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`](https://github.com/screenrig/plugin). It bundles the
skill and CLI your agent uses to operate screens. Terminal agents can run the
[install commands](https://screenrig.ai/docs/start.md#official) directly.

On the first run your agent reuses your contact email, asking only when it is missing. It uses the organization name you already provided, or defaults to Screens, and runs `screenrig agent enroll --email ADDRESS --organization NAME`. Enrollment creates the identity, organization, Screens project, membership and credentials, and emails you an invitation. 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](https://screenrig.ai/docs/players.md) 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](https://screenrig.ai/docs/start/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](https://screenrig.ai/docs/start/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](https://screenrig.ai/docs/start/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](https://screenrig.ai/docs/start/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](https://screenrig.ai/docs/start/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](https://screenrig.ai/docs/start/chatgpt/)** is OpenAI’s coding
  agent. Run the marketplace commands below in your terminal, then start Codex. In
  ChatGPT itself, use [ChatGPT dots](https://screenrig.ai/docs/start/dots/).
- **[Gemini Spark](https://screenrig.ai/docs/start/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](https://screenrig.ai/docs/start.md#official) below in your
  terminal, then start Grok Build. It has no separate guide.

Standard is free within its included monthly allowances. Buying extra usage is optional. Image generation is metered separately. [See allowances and plans](https://screenrig.ai/pricing.md).

## Connect your first screen

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

1. **Create your screenRIG project.** Give your agent your actual contact email
   and use the organization name already provided, or default to Screens. 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. **Install and launch your Player.** Follow
   [Player downloads & setup](https://screenrig.ai/downloads.md) to install the
   web app on the device driving your screen, then launch it.
   Send the pairing code shown there to your agent.
3. **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. **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?](https://screenrig.ai/docs/start.md#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](https://screenrig.ai/docs/start/claude-code/) or
[ChatGPT Codex](https://screenrig.ai/docs/start/chatgpt/) 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](https://screenrig.ai/docs/start.md#run-the-bundled-cli)
puts the plugin launcher on `PATH` for the session, so later examples use
`screenrig`.

<a id="official"></a>

## The official install

Install the official plugin from
[`github.com/screenrig/plugin`](https://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.

### Run the bundled CLI

Node.js 22.11 or newer 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.

### 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, uses the organization name already provided, or defaults to Screens, and runs
`screenrig agent enroll --email ADDRESS --organization "Screens"`. Enrollment always
creates a new project, even if your email already has a login, and emails a
project-member invitation. Add `--intent advertising` when the project's purpose
is buying ads rather than pairing screens.

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** 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](https://screenrig.ai/docs/authentication.md).

Before pairing or buying, `screenrig project capabilities` reads what this
project can actually do: the plan id, 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.

One login can belong to many projects. Email and passkeys belong to
the person, while screens, media, balances, and allowances belong to a project.
Use `screenrig invitations create --email ADDRESS` to invite a project member.
Email invitations expire after seven days. Explicit member links from
`screenrig invitations create --email ADDRESS --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.

### 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 | Node.js older than 20.11 | `node --version`, then install Node.js 22.11 or newer |
| `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 "Screens"`; 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 |
| A `credits_low` warning | The integer credit meter is below its warning threshold | Until 1 Jan 2027 usage is free within reason, so continue the requested work. Standard's free monthly allowances continue after that; extra usage is optional prepaid |
| `screen list` returns nothing | No Player is on the glass yet | Open the [Player](https://screenrig.ai/docs/players.md), then `screenrig screen list` |

<a id="signage-buying-or-selling"></a>

## 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 "Screens"` 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 spends only the quoted completed-play price,
settled in credits on the project's shared balance: the quoted price is held
against eligible credits when a play is scheduled and settles only for a
completed play. No card, invoice, or checkout is involved, and included and
promotional grants cannot fund paid ads; purchased and ad-earned credits can.

**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,
serving fee, and net with `ads reports delivery`. A changed effective rate
pauses every affected campaign until each buyer accepts a fresh quote.

Open **Invitations** in the dashboard to invite project members or ad buyers,
view invitation status, and cancel pending invitations. Sellers also manage
buyer membership scope and revoke buyer access; revocation stops new ad plays
while preserving financial history.

[Rates, serving fees, and credit funding](https://screenrig.ai/pricing.md#advertising).

## Next

Open the guide for [Meta Muse](https://screenrig.ai/docs/start/muse/),
[Grok Bot](https://screenrig.ai/docs/start/grok-bot/),
[ChatGPT dots](https://screenrig.ai/docs/start/dots/),
[Claude Code](https://screenrig.ai/docs/start/claude-code/),
[Hermes](https://screenrig.ai/docs/start/hermes/),
[ChatGPT Codex](https://screenrig.ai/docs/start/chatgpt/), or
[Gemini Spark](https://screenrig.ai/docs/start/gemini-spark/), then the
[Players](https://screenrig.ai/docs/players.md), the
[CLI reference](https://screenrig.ai/docs/cli.md),
[Compose a still](https://screenrig.ai/docs/compose.md), or the
[advertising rates and fees](https://screenrig.ai/pricing.md#advertising).