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. 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, 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. Boot-only flags such as ui.mascot.soundEnabled, ui.muted, and explicit deepLink.* overrides 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.
RoverBook Settings Live In Workspace
RoverBook owner settings are intentionally not boot-config fields. Use Rover Workspace Settings 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: Standard Rover keeps action-oriented Rover behavior enabled and includes RoverBook by default, while RoverBook 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 a canonical task envelope such as { url, goal, capabilityId, args, target, identity, execution, accept, policy } to https://agent.rtrvr.ai/v1/tasks. Compatibility shorthands like { url, prompt } and { url, shortcutId } still work. 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 and blocks sibling subdomains unless you explicitly allow them. |
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 } | 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. |
Public Agent Tasks (Cloud Site Config)
| 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/tasks`, 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. 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. |
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 Rover task 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 Rover tasks 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; legacy `visibleCueLabel` remains compatibility input only. |
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.motion.intensity | 'calm' | 'balanced' | 'expressive' | Controls the overall motion and ambient depth system for the presence pill and centered stage. |
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.mp4Url | string | Custom mascot MP4 URL. |
ui.mascot.webmUrl | string | Custom mascot WebM URL. |
ui.mascot.soundEnabled | boolean | Owner gate for mascot audio. Rover keeps mascot sound unavailable unless this is explicitly enabled. |
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. |
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 } | Legacy compatibility input for first-run intro timing. 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. |