Configuration
Full rover('boot', config) reference.
Workspace snippet generation includes required fields and only non-default overrides you set, so output stays minimal and accurate.
Generated Rover key snippets always include core runtime identity/policy fields:siteId,publicKey,allowedDomains,siteMode,domainScopeMode,externalNavigationPolicy, and optional navigation.crossHostPolicy.
Domain scope quick reference: with registrable_domain, example.com allows the apex host and all subdomains, while *.example.com allows subdomains only. A more specific plain host like app.example.com allows that host and its subdomains, not sibling hosts like www.example.com.
Rover v2 hard-isolates task state: each normal user send starts a fresh task boundary (new prevSteps and tab scope). Only ask_user answers continue the same boundary.task.followup.* controls optional heuristic chat-cue carryover only, never state carryover.
Workspace uses a Guided + Expert model: common settings are front-and-center, while low-level runtime controls live behind Expert mode. Visitor profile fields are intentionally not static workspace inputs; pass live identity with rover.identify(...).
Workspace shortcuts, greeting, voice, AI access, and page capture are persisted in cloud site-config and fetched at runtime via /v2/rover/session/open.Save Site Config writes to the currently selected key target, while Create Rover Site Key auto-saves the current site config to the newly created key. Global cloud extraction settings remain separate for the extension and do not configure Rover embeds. If the same field is set in both cloud config and boot snippet, boot config wins. Effective shortcut limits come from the authenticated site-key policy, while ui.muted and deepLink remain boot-only and are not persisted through these workspace endpoints.
RoverBook Setup Lives In Workspace
RoverBook owner settings are intentionally not boot-config fields. Use the Rover Workspace setup view for per-site interview questions and webhook subscriptions, then use the RoverBook analytics views for read-only AX reporting.
Site mode is also a Workspace concern: Full Rover agent keeps action-oriented Rover behavior enabled, while RoverBook analytics-only keeps the key embed-oriented and action-restricted.
Visiting-agent identity now comes primarily from Rover task/session attribution. Public task callers can send an agent object, Rover can use lightweight heuristic headers when that is missing, and only then do advanced local fallbacks such as RoverBook identityResolver apply.
Site owners get siteId, publicKey, and siteKeyId from Workspace for installing Rover. Anonymous AI callers do not need those values when they use POST https://agent.rtrvr.ai/v1/tasks.
For AI and CLI-triggered entrypoints, prefer exact shortcut IDs for repeatable journeys: ?rover_shortcut=checkout_flow. Use raw prompt deep links like ?rover=book%20a%20flight for ad hoc tasks.
AI and CLI tools can also bypass deep links entirely by posting { url, prompt } to https://agent.rtrvr.ai/v1/tasks. The returned task URL supports JSON polling, SSE, NDJSON, continuation input, and cancel. Browser-capable tasks may also include a clean receipt-based open URL and an optional readable browserLink alias. Use Prefer: execution=cloud when the caller needs guaranteed browserless execution today.
For runtime request/response schemas and stale conflict envelopes, see API Reference.
Core Identity
| Option | Type | Description |
|---|---|---|
siteIdreq | string | Workspace site identifier for this embed deployment. |
publicKeyreq | string | Public Rover site key (`pk_site_*`) generated in Workspace. Required for cloud-backed runtime calls. |
siteKeyId | string | Optional key ID returned by Workspace. Included in generated snippets. |
apiBase | string | Optional API base override for custom proxying or self-managed backend routes. Rover uses `/v2/rover/*` under this base. |
visitorId | string | Stable visitor identifier. Auto-generated when omitted unless checkpointing auto visitor is disabled. |
visitor | { name?: string; email?: string } | Optional visitor profile used for greeting personalization. Recommended flow is async updates via rover.identify(...) after login/user hydration. |
sessionId | string | Explicit session identifier. Useful when you need hard control over restore boundaries. |
sessionScope | 'shared_site' | 'tab' | Cross-tab shared session (`shared_site`) or strict tab isolation (`tab`). |
workerUrl | string | Custom worker bundle URL, primarily for self-hosting and strict CSP setups. |
mode | 'full' | 'safe' | Top-level runtime mode. `safe` is constrained execution mode. |
Domain Guardrails & Navigation
| Option | Type | Description |
|---|---|---|
allowedDomainsreq | string[] | Allowed host/domain patterns for Rover runtime. Supports host (`example.com`), wildcard (`*.example.com`), exact host (`=app.example.com`), and URL-shaped entries (`https://example.com/path`, normalized to host). In `registrable_domain`, plain `example.com` covers the apex host and subdomains. |
domainScopeMode | 'registrable_domain' | 'host_only' | How Rover interprets plain `allowedDomains` entries. `registrable_domain` means apex + subdomains for the listed host, while `host_only` makes plain entries exact-host only. |
externalNavigationPolicy | 'open_new_tab_notice' | 'block' | 'allow' | Out-of-scope navigation policy for external domains. |
navigation.crossHostPolicy | 'same_tab' | 'open_new_tab' | In-scope cross-host navigation policy (for allowed destinations that change host). |
openOnInit | boolean | Open the Rover panel immediately after boot. |
deepLink | { enabled?: boolean; promptParam?: string; shortcutParam?: string; consume?: boolean } | Opt-in URL-triggered Rover. `?rover=book%20a%20flight` auto-opens Rover and runs the prompt, while `?rover_shortcut=checkout_flow` resolves an exact shortcut ID. Shortcut IDs take precedence when both params are present. |
allowActions | boolean | Allow/deny action tools (click/fill/navigate). Set false for read-only assistance. |
tabPolicy.observerByDefault | boolean | Observer behavior preference for multi-tab coordination. |
tabPolicy.actionLeaseMs | number | Control lease duration used by shared session coordinator. |
Task Routing
| Option | Type | Description |
|---|---|---|
taskRouting.mode | 'auto' | 'act' | 'planner' | Route tasks directly to ACT, always planner, or automatic routing. In server-authoritative mode this is sent as requestedMode on /v2/rover/command. |
taskRouting.actHeuristicThreshold | number | Complexity threshold used only when taskRouting.mode is auto. |
taskRouting.plannerOnActError | boolean | In auto mode, retry through planner only when ACT does not produce a usable outcome. Planner fallback does not run after usable ACT success. |
Task Context
| Option | Type | Description |
|---|---|---|
taskContext.resetMode | 'auto' | 'ask' | 'off' | Advisory prompt-level reset suggestion policy; run boundaries are still hard-isolated per new user prompt. |
taskContext.inactivityMs | number | Optional inactivity hint used by task continuity logic. |
taskContext.suggestReset | boolean | Allow Rover to surface reset suggestions when continuity is unclear. |
taskContext.semanticSimilarityThreshold | number (0..1) | Optional similarity hint for continuity scoring. |
task.followup.mode | 'heuristic_same_window' | Enable heuristic follow-up chat cues for fresh tasks in the same window. |
task.followup.ttlMs | number | Max age of prior completed/ended task output eligible for follow-up cue carryover. |
task.followup.minLexicalOverlap | number (0..1) | Minimum normalized lexical overlap between last task intent and current prompt to attach chat cues. |
Checkpointing
| Option | Type | Description |
|---|---|---|
checkpointing.enabled | boolean | Cloud checkpoint sync is enabled by default in Rover v2. Set false to disable. |
checkpointing.autoVisitorId | boolean | Auto-generate visitor ID when checkpointing is enabled. |
checkpointing.flushIntervalMs | number | Push interval for checkpoint writes. |
checkpointing.pullIntervalMs | number | Pull interval for checkpoint refresh. |
checkpointing.minFlushIntervalMs | number | Minimum debounce interval for checkpoint writes. |
checkpointing.ttlHours | number | Checkpoint document TTL in hours. |
API Execution
| Option | Type | Description |
|---|---|---|
apiMode | boolean | Force cloud API mode on/off instead of automatic behavior. |
apiToolsConfig.mode | 'allowlist' | 'profile' | 'none' | Controls additional tool exposure in API mode. |
apiToolsConfig.enableAdditionalTools | string[] | Additional first-party tool names to enable. |
apiToolsConfig.userDefined | string[] | User-defined tool identifiers available to the runtime. |
Public Agent Tasks (Cloud Site Config)
| Option | Type | Description |
|---|---|---|
siteConfig.aiAccess.enabled | boolean | Turns on the neutral public task protocol for this site. When enabled, the generated snippet can expose the source-visible discovery marker and `POST https://agent.rtrvr.ai/v1/tasks` becomes available for host-only `url + prompt` launches. |
siteConfig.aiAccess.allowPromptLaunch | boolean | Allow natural-language prompt launches through the public task resource. |
siteConfig.aiAccess.allowShortcutLaunch | boolean | Allow exact saved shortcut execution through the public task resource. |
siteConfig.aiAccess.allowCloudBrowser | boolean | Allow hosted-browser execution for browserless callers. Today, callers should use `Prefer: execution=cloud` when they need a guaranteed browserless path. |
siteConfig.aiAccess.allowDelegatedHandoffs | boolean | Allow Rover on other Rover-enabled sites to create delegated child tasks into this site through `POST /v1/tasks/{id}/handoffs` so multi-site workflows can share one lineage. |
siteConfig.aiAccess.debugStreaming | boolean | Opt-in richer planner/page refs for advanced debugging. Normal public task runs already stream full status, tool, message, and final output. |
Telemetry
| Option | Type | Description |
|---|---|---|
telemetry.enabled | boolean | Enable Rover runtime telemetry event batching to cloud backend. |
telemetry.sampleRate | number (0..1) | Sampling ratio for telemetry events (1 = all events, 0.1 ≈ 10%). |
telemetry.flushIntervalMs | number | Flush cadence for buffered telemetry events. |
telemetry.maxBatchSize | number | Maximum number of telemetry events sent per flush request. |
telemetry.includePayloads | boolean | Include richer per-event payload details (debug/tool context). Higher storage/network cost and may contain sensitive runtime content. |
Production default: telemetry.enabled=true, sampleRate=1, includePayloads=false. Enable payloads only for targeted debugging windows.
External Web Context & Client Tools
| Option | Type | Description |
|---|---|---|
tools.web.enableExternalWebContext | boolean | Allow best-effort cloud context fetch for inaccessible external tabs. |
tools.web.scrapeMode | 'off' | 'on_demand' | On-demand scrape of active external tab context when needed. |
tools.web.allowDomains | string[] | Optional allowlist for external context fetch hostnames. |
tools.web.denyDomains | string[] | Optional denylist for external context fetch hostnames. |
tools.client | ClientToolDefinition[] | Runtime-registered client tools. Usually configured in application code, not in script snippets. |
UI & Branding
| Option | Type | Description |
|---|---|---|
ui.agent.name | string | Assistant display name and runtime context name passed to the model. |
ui.mascot.disabled | boolean | Disable mascot video in launcher/header. |
ui.mascot.mp4Url | string | Custom mascot MP4 URL. |
ui.mascot.webmUrl | string | Custom mascot WebM URL. |
ui.muted | boolean | Start Rover UI muted on first load. If the visitor later toggles sound in Rover, their stored browser preference overrides this default. |
ui.thoughtStyle | 'concise_cards' | 'minimal' | UI thought rendering style preference. |
ui.panel.resizable | boolean | Enables adaptive panel resizing across devices: desktop freeform resize, phone/tablet snap heights, and remembered size per device class. |
ui.showTaskControls | boolean | Show/hide task lifecycle controls in the UI. |
ui.shortcuts | RoverShortcut[] | Suggested journeys. Rover supports up to 100 stored shortcuts and renders up to 12 enabled shortcuts by default; site-key policy can lower these limits. |
ui.greeting | { text?: string; delay?: number; duration?: number; disabled?: boolean } | Greeting bubble configuration. Supports {name} placeholder and async profile updates via rover.identify(...). |
ui.voice | { enabled?: boolean; language?: string; autoStopMs?: number } | Browser dictation on supported Chromium browsers. Rover fills the draft live, waits for post-speech silence before stopping, and the user still reviews and sends manually. |
pageConfig | RoverPageCaptureConfig | Optional top-level page capture overrides such as disableAutoScroll, settle timing, and sparse-tree retry settings. |