Skip to main content
Connect Revyl over MCP so your coding agent can run the current app source, control cloud devices, and verify changes.

​
Install the Revyl CLI

The Revyl Cursor Marketplace plugin is coming soon. Until it launches, Cursor, Claude Code, and Codex connect through the Revyl CLI. Install the Revyl CLI:

​
Cursor

Coming soon: the official Revyl Marketplace plugin will bundle the MCP configuration, focused skills, routing rule, hooks, and a pinned Revyl runtime. For now, use the CLI-based setup below.
From the app repository, authenticate and install the MCP dev-loop skill:
Create .cursor/mcp.json in the repository:
Restart Cursor if it was already open when you installed the CLI. Start a new Agent chat and ask:
The dev profile exposes 11 focused setup, dev-loop, and device tools, including setup_status. It is intentionally narrower than the core and full profiles. Use the CLI or a broader MCP profile for test, workflow, and other management operations. The command above installs the MCP-specific revyl-mcp-dev-loop skill. The default revyl skill install command installs the separate revyl-cli-* fallback family and is not required for this MCP setup. When the Marketplace plugin launches, it will bundle its MCP skills automatically; do not install a second copy.

​
How the Marketplace plugin runtime will work

When Cursor starts the future plugin MCP server, the plugin launcher will use an explicitly configured REVYL_BINARY when present. Otherwise it will:
  1. read the runtime version and per-platform SHA-256 values pinned in the plugin release;
  2. select the matching macOS, Linux, or Windows asset from the immutable Revyl CLI GitHub Release;
  3. reuse the versioned cached executable only when its SHA-256 still matches;
  4. download a missing or corrupt executable to a temporary file with a bounded timeout, verify it, install it atomically, and verify the cached file again;
  5. start the MCP server over the same protected standard input and output streams.
The default cache is under $XDG_CACHE_HOME or $HOME/.cache/revyl/cursor-plugin on macOS and Linux, and %LOCALAPPDATA%\Revyl\cursor-plugin on Windows. A new plugin runtime pin uses a new versioned directory. A corrupt cached executable is never run and is replaced on the next online start. The first start of a new runtime needs access to its GitHub Release; later starts can use the verified cache. Bootstrap failures are written only to standard error so they cannot corrupt MCP messages. The plugin readiness hook reports missing prerequisites but never downloads or installs software itself.

​
Other CLI-based MCP clients

​
Claude Code

Open a new terminal, authenticate, and run from the app repository:

​
Codex

Open a new terminal, authenticate, and run from the app repository:

​
Setup recovery

The agent calls start_dev_loop first. When setup is ready, Revyl returns the viewer immediately. Otherwise the result contains one structured remediation:
  • auth_required or auth_expired: run remediation.command.
  • cloud_secret_required: add remediation.env_name as a Runtime Secret and start a new Cloud session; do not retry when restart_required is true.
  • project_not_initialized: run remediation.command once in remediation.working_directory.
  • project_ambiguous: choose one remediation.candidate_roots value and retry with that exact project_dir.
  • project_invalid: repair remediation.config_path before retrying.
After one remediation, the agent retries start_dev_loop once. A second failure is reported instead of entering a setup loop. setup_status provides the same secret-free setup diagnostics when explicitly requested, but it is not required before a normal dev loop.

​
Cursor Cloud Agents

Cloud Agents do not inherit the CLI installation or credentials from your local machine. Until the Marketplace plugin launches:
  1. Install the Revyl CLI in the Cloud environment setup.
  2. Include the project .cursor/mcp.json and revyl-mcp-dev-loop skill from the Cursor setup above.
  3. Add REVYL_API_KEY as a Runtime Secret.
  4. Start a new Cloud Agent so the MCP process receives the CLI and secret.
  5. Ask the agent to run the app with a remote build.
After the Marketplace plugin launches, its pinned runtime will replace the separate CLI installation. REVYL_API_KEY will still need to be configured as a Runtime Secret before starting a fresh Cloud Agent.

​
Manual CLI fallback

Use the standalone CLI for CI, terminal workflows, unsupported MCP clients, offline environments, advanced operations, or recovery. Install it with the platform command above, then run the bounded loop from the app directory:
Run from the actual app root in a monorepo. If framework detection is wrong, rerun initialization with one explicit provider:
Use revyl dev list, explicit contexts, or revyl dev attach only when intentionally reusing an existing session. See the full dev-loop guide for framework-specific behavior.

​
Verify

Start a new agent chat and ask:
The agent should share the viewer URL immediately, return device-backed evidence, and stop the device when finished.