Configuration
Full rover('boot', config) reference.
Workspace snippet generation includes required fields plus explicit guide-flow defaults for voice narration, Action Spotlight, and scroll-off page capture, so new installs are self-documenting.
Generated Rover key snippets always include the core runtime identity and scope fields:siteId,publicKey,allowedDomains,siteMode, and domainScopeMode. Rover handles tab behavior automatically: outside-scope pages open in a new tab with notice, and allowed-host hops use smart tab selection.
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. In host_only, plain entries become exact-host rules, so sibling subdomains are blocked unless you explicitly list them.
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, presence, task-flow defaults, inputs, AI launch, agent discovery policy, page capture, and site-owned mascot appearance controls 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. Explicit boot-only overrides such as deepLink.* are not persisted through these workspace endpoints, but browser deep-link availability still follows persisted siteConfig.aiAccess.enabled unless you override it manually at boot.
Experience resolution order is fixed: explicit boot/snippet overrides win, then persisted siteConfig.experience, then Rover defaults. Discovery still publishes from siteConfig.agentDiscovery, but the visible Rover V3 surface is presence-pill first, then centered stage, then focus stream.
Agent Analytics Settings Live In Workspace
Agent analytics owner settings are intentionally not boot-config fields. Use Rover Workspace Settings for per-site interview questions and webhook subscriptions, then use the analytics views for read-only AX reporting.
Site mode is also a Workspace concern: Standard Rover keeps action-oriented Rover behavior enabled and includes Agent analytics by default, while Agent analytics only keeps the key embed-oriented and action-restricted.
Visiting-agent identity now comes primarily from Rover run/session attribution. Public A2W run callers can send an agent object, Rover can use lightweight heuristic headers when that is missing, and only then do advanced local analytics fallbacks such as 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/a2w/runs or chatbot GET execution.
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 a canonical A2W run envelope such as { url, prompt, capabilityId, args, target, identity, execution, accept, policy } to https://agent.rtrvr.ai/v1/a2w/runs. goal remains accepted as a compatibility alias. For saved journeys, send { url, shortcutId }. URL-fetch chatbots can use GET /v1/a2w/runs?url=...&prompt=...&execution=cloud&wait=25&format=markdown, follow rover_exec, or resolve a browser deep link with /v1/a2w/from-url. The returned run URL supports JSON polling, markdown polling, SSE, NDJSON, continuation input, and cancel.
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 and blocks sibling subdomains unless you explicitly allow them. |
openOnInit | boolean | Open the Rover panel immediately after boot. |
deepLink | { enabled?: boolean; promptParam?: string; shortcutParam?: string; consume?: boolean } | Advanced boot/runtime override for URL-triggered Rover. If you omit `deepLink.enabled`, Rover derives whether `?rover=` and `?rover_shortcut=` are available from persisted `siteConfig.aiAccess.enabled`. `promptParam`, `shortcutParam`, and `consume` stay boot-level overrides for manual SDK installs. |
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. |
Agent-to-Web (A2W) Access
| Option | Type | Description |
|---|---|---|
siteConfig.businessType | RoverBusinessType | Tunes the composer's rotating placeholder hints and the runtime's generated quick actions when the site has fewer than three explicit shortcuts. |
siteConfig.aiAccess.enabled | boolean | Canonical owner-facing launch switch. When enabled, Rover exposes `POST https://agent.rtrvr.ai/v1/a2w/runs`, chatbot GET execution, browser deep links like `?rover=...`, and exact shortcut deep links like `?rover_shortcut=...`. Workspace/Webflow default this on for new sites. |
siteConfig.aiAccess.allowCloudBrowser | boolean | Allow hosted-browser execution for browserless callers. POST callers should use `Prefer: execution=cloud, wait=10`; URL-fetch chatbots should use GET with `execution=cloud&wait=25&format=markdown`. |
siteConfig.aiAccess.allowDelegatedHandoffs | boolean | Allow Rover on other Rover-enabled sites to create delegated child runs into this site through `POST /v1/a2w/runs/{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 A2W runs already stream full status, tool, message, and final output. |
Agent Discovery (Cloud Site Config)
| Option | Type | Description |
|---|---|---|
siteConfig.agentDiscovery.enabled | boolean | Persisted site-level switch for Rover's public discovery surfaces. Turn this off only when you want A2W run access without publishing the inline marker, page manifest, hidden landmark, or the visible Rover seed/presence cue. |
siteConfig.agentDiscovery.preferExecution | 'auto' | 'browser' | 'cloud' | Published preference for how external agents should execute A2W runs by default. Callers can still request a specific mode explicitly. |
siteConfig.agentDiscovery.agentCardUrl | string | Published path for the broad interop card used by `service-desc` and generic agent discovery. |
siteConfig.agentDiscovery.roverSiteUrl | string | Published path for Rover's authoritative rich discovery profile. This is the canonical capability graph and display-policy artifact. |
siteConfig.agentDiscovery.llmsUrl | string | Optional published `llms.txt` location. Advisory support only, not the action contract. |
siteConfig.agentDiscovery.hostSurfaceSelector | string | Optional CSS selector for an existing site-owned assistant/help surface that Rover should annotate or attach to in integrated mode. |
siteConfig.agentDiscovery.discoverySurface.mode | 'silent' | 'beacon' | 'integrated' | 'debug' | Discovery ladder mode. `beacon` is the production default for machine-readable publication, `silent` keeps only protocol + semantics, `integrated` binds to an owner surface, and `debug` exposes the old explicit debug cue/action sheet. |
siteConfig.agentDiscovery.discoverySurface.branding | 'site' | 'co' | 'rover' | Controls the branding voice published in discovery metadata and any debug-only cue surfaces. The underlying Rover protocol and analytics remain unchanged. |
siteConfig.agentDiscovery.discoverySurface.hostSurface | 'auto' | 'existing-assistant' | 'floating-corner' | 'inline-primary' | Hints how Rover should place or bind its compact visible surface. Prefer `auto` unless the site already has a first-party assistant entrypoint. |
siteConfig.agentDiscovery.discoverySurface.actionReveal | 'click' | 'focus' | 'keyboard' | 'agent-handshake' | Controls when Rover expands from the compact beacon into the action sheet or integrated surface. |
siteConfig.agentDiscovery.discoverySurface.beaconLabel | string | Optional human-facing copy mirrored into the visible Rover seed/presence CTA. `beaconLabel` is the canonical public field name. |
siteConfig.agentDiscovery.discoverySurface.agentModeEntryHints | string[] | Optional short hints published to external agents about how to enter Rover mode on the site when a custom assistant surface or workflow exists. |
Experience Contract (Cloud Site Config)
| Option | Type | Description |
|---|---|---|
siteConfig.experience.presence.assistantName | string | Primary presence name used in the minimized seed, centered stage header, and task surfaces. |
siteConfig.experience.presence.ctaText | string | Human-facing call to action for the minimized seed/presence and published discovery metadata. |
siteConfig.experience.presence.defaultAnchor | 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'bottom-center' | Initial placement for the minimized presence before Rover applies remembered browser placement. |
siteConfig.experience.shell.openMode | 'center_stage' | Desktop shell mode. Rover V3 opens as a centered stage instead of a legacy docked chat panel. |
siteConfig.experience.shell.mobileMode | 'fullscreen_sheet' | Mobile shell mode. Rover V3 uses a full-screen sheet for focused task execution. |
siteConfig.experience.stream.maxVisibleLiveCards | number | How many live step cards stay expanded in the focus stream before older steps collapse into logs. |
siteConfig.experience.stream.artifactAutoMinimize | boolean | Auto-minimize large artifacts while Rover is actively working so the step stack stays readable. |
siteConfig.experience.inputs.voice | boolean | Enables voice input in the bottom dock when the browser supports it. |
siteConfig.experience.inputs.files | boolean | Enables first-class file attachments in the bottom dock. Rover uploads files into the same CloudFileDescriptor / LLMDataInput pipeline used by cloud and relay flows. |
siteConfig.experience.inputs.acceptedMimeGroups | ('images' | 'pdfs' | 'office' | 'text')[] | High-level attachment classes Rover accepts in the runtime dock and publishes in discovery metadata. |
siteConfig.experience.inputs.attachmentLimit | number | Maximum number of attachments a visitor can stage in the dock for a single prompt. |
siteConfig.experience.experienceMode | 'guided' | 'minimal' | Owner-facing experience preset. Guided makes guide flows narrate and highlight by default; minimal keeps narration and highlights quiet by default while preserving visitor opt-in controls. |
siteConfig.experience.audio.narration.enabled | boolean | Owner gate for browser Web Speech step narration. Visitors still get a site-scoped speaker toggle when supported. |
siteConfig.experience.audio.narration.defaultMode | 'guided' | 'always' | 'off' | Controls when Rover reads short action, question, checkpoint, and final-response cues aloud: guide flows, every run, or off unless the visitor turns it on. |
siteConfig.experience.audio.narration.rate | number | Narration rate, clamped between 0.85 and 1.15 for clarity. |
siteConfig.experience.audio.narration.language | string | Preferred narration and dictation language. |
siteConfig.experience.motion.intensity | 'calm' | 'balanced' | 'expressive' | Controls the overall motion and ambient depth system for the presence pill and centered stage. |
siteConfig.experience.motion.actionSpotlight | boolean | Highlights the page element Rover is acting on during click, type, select, scroll, and related tool actions. Set false to disable. |
siteConfig.experience.motion.actionSpotlightColor | "#RRGGBB" | Sets the Action Spotlight ring and glow color. Workspace and Webflow expose this as a swatch plus hex picker; invalid values fall back to the default orange. |
siteConfig.experience.motion.actionSpotlightRunKinds | ('guide' | 'task')[] | Controls which shortcut run kinds show Action Spotlight by default. Per-action ui.highlight may override this default unless the visitor has explicitly hidden highlights. |
siteConfig.experience.theme.surfaceStyle | 'glass' | 'solid' | Defines whether the centered stage uses Rover’s glass surface treatment or a more solid panel style. |
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. |
Boot-Time UI Overrides
| 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.imageUrl | string | Custom mascot image URL. Works by itself or as the fallback/poster for custom video mascots. |
ui.mascot.mp4Url | string | Custom mascot MP4 URL. Video is preferred when MP4 or WebM is provided. |
ui.mascot.webmUrl | string | Custom mascot WebM URL. Video is preferred when MP4 or WebM is provided. |
ui.mascot.soundEnabled | boolean | Owner gate for mascot audio. Video mascots start silent unless this is explicitly enabled; image-only mascots stay silent. |
ui.muted | boolean | Initial mascot mute state only when mascot sound is enabled. If the visitor later toggles sound in Rover, their stored preference for that Rover site 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. Set shortcut.runKind to 'guide' for onboarding/demo journeys that should use guided narration and Action Spotlight defaults. |
ui.experience | RoverSiteExperience | Canonical boot-time override for the Rover V3 presence pill, centered stage shell, focus stream, inputs, motion, and theme. Workspace writes the same contract into `siteConfig.experience`. |
ui.greeting | { text?: string; delay?: number; duration?: number; disabled?: boolean } | First-run intro timing override. Prefer `ui.experience.presence.*` and `siteConfig.experience` for Rover V3. |
ui.voice | { enabled?: boolean; language?: string; autoStopMs?: number } | Compatibility input for browser dictation defaults. Prefer `ui.experience.inputs.voice` plus `siteConfig.experience.inputs` for Rover V3. |
pageConfig | RoverPageCaptureConfig | Optional top-level page capture overrides such as disableAutoScroll, settle timing, and sparse-tree retry settings. Generated installs default to { disableAutoScroll: true }; set false only when the owner enables automatic page scrolling. |