docs
Log in

Supervised sessions

Rove is the supervised browser for agents. Your agent drives a real browser; you, or a person you choose, watch it live, take control when it matters, then hand it back.

How a handoff works

  1. Your agent starts a supervised session: supervised: true on POST /v1/browser/session, session({ supervised: true }) in an SDK, or the MCP tool start_supervised_session. Supervised sessions need an rvp_live_ key; test keys use mock actions and have no browser to stream.
  2. It mints a viewer link for that session: POST /v1/browser/sessions/{session_id}/viewer-grants, createViewerGrant (Node), create_viewer_grant (Python and MCP). The answer carries a viewer_url, a one-time admission_code and expires_in_seconds.
  3. The person opens the viewer_url in their own browser and watches the agent work, with a running list of its actions.
  4. They select Take control. Control is exclusive: while they hold it the agent can't click or type, and its actions are refused with 409.
  5. They select Return to agent. Before its next action the agent must read the page again (get_a11y_tree or screenshot), so it never acts on a page it hasn't seen.
  6. Either side ends the session: Stop session in the viewer, or close_session. Closing releases the browser.

Start one

With the MCP server, add Rove to Claude, Cursor or VS Code:

{
  "mcpServers": {
    "rove": { "command": "npx", "args": ["-y", "@roveapi/mcp"] }
  }
}

Then ask your agent: "Start a supervised session, open the vendor dashboard, and send me the viewer link before you approve anything." With no key set, the agent signs you in with your email from inside the chat.

From Node, with @roveapi/browser:

import { BrowserClient } from '@roveapi/browser'

const rove = new BrowserClient({ apiKey: process.env.ROVE_API_KEY! })

// Your agent drives this session; a person can take control at any time.
const session = await rove.session({ supervised: true })
await session.navigate('https://dashboard.vendor.example/invoices')

// A one-time link for the person supervising.
const { viewerUrl } = await rove.createViewerGrant(session.id)
console.log(`Watch or take control: ${viewerUrl}`)

From Python, with roveapi:

import os

from roveapi import BrowserClient

rove = BrowserClient(api_key=os.environ["ROVE_API_KEY"])
session = rove.session(supervised=True)
session.navigate("https://dashboard.vendor.example/invoices")
grant = rove.create_viewer_grant(session.id)
print("Watch or take control:", grant["viewer_url"])
rove.close()

Route the handoff to your own operators

Building agents for your customers or your team? Every supervised session has a link you can hand to whoever should step in.

  • Mint a fresh link for each person, when they step in. A link works once, from the site it was made for, and expires after expires_in_seconds. A used link can't be opened again.
  • Deliver it however your product already reaches people: your queue, chat or email. Treat the link as a short-lived secret: send it only to the intended operator, never post it publicly, and never send the target site's credentials alongside it.
  • The link opens Rove's viewer in the operator's browser. They watch, take control and hand back there; nothing to embed.
  • Give each agent its own API key. The viewer shows the session and the key that started it.
  • Watch the whole fleet. Your account's Sessions page lists every supervised session with its status and who has control, and you can open or stop any of them.
  • One rate for agent and operator minutes, so a handoff never changes the price. See pricing and Credits and pricing.

Built so you stay in charge

  • One driver at a time. While a person is in control, the agent can't click or type.
  • Viewer links work once, from the site they were made for.
  • Every supervised session runs in its own browser worker.
  • Sign-ins stay with the API key's browser profile, so you log in once, not every session. Agents can list and clear that history (list_history, clear_history) or delete the profile (delete_profile).
  • After you hand back, the agent re-reads the page before it acts.

Use it responsibly

Use supervised sessions only on sites and accounts you own or are authorized to operate, and only when a brief interruption is safe; a handoff is not a critical-workflow or recovery guarantee. Don't use it to bypass CAPTCHAs, anti-bot protections, access controls or a site's terms.

Reference

Rove — the supervised browser for agents