Configuration
What belongs in Workspace, what the production tag carries, and the supported browser SDK overrides.
Most sites should configure Rover in Workspace and install the generated tag once. The tag identifies the site. Rover loads the current domain policy, journeys, knowledge, audience rules, appearance, actions, and analytics settings when a session opens.
Start with the generated tag
Do not hand-build production credentials. Copy the current snippet from Workspace Install. Routine setting changes need no code deploy. If you rotate the production site key, replace any snippet you copied into your site.What Workspace owns
| Workspace area | Configuration it owns |
|---|---|
| Install | Production tag, allowed domains, site mode, install status, AI discovery files, and cloud-sandbox access. |
| Journeys | Demo, onboarding, support, and task flows, including preview and live state. |
| Knowledge | Bounded facts Rover may state. |
| Audience | Identity provider guidance, verified context lookup, name use, and conversation memory. |
| Appearance | Name, presence, shortcuts, mascot, voice, motion, and theme. |
| Customize | Business purpose, instructions, page scopes, routing, model tiers, and owner actions. |
| Analytics | Collection, consent, goals, product events, funnels, retention, and server collection credentials. |
These settings are versioned and resolved by Rover's backend. Use browser configuration only when the value must come from the page at runtime, such as signed-in identity, or when an advanced integration deliberately needs a local override.
The production tag
<!-- Copy the generated values from Workspace > Install -->
<script
src="https://rover.rtrvr.ai/embed.js?v=YOUR_SITE_KEY_ID"
async
data-site-id="YOUR_SITE_ID"
data-public-key="pk_site_YOUR_PUBLIC_KEY"
data-site-key-id="YOUR_SITE_KEY_ID"></script>| Attribute | Purpose |
|---|---|
data-site-id | Selects the Rover site. |
data-public-key | Public browser credential generated for that site. It is not a server secret. |
data-site-key-id | Identifies the active site key and is also used as the script cache-buster. |
Allowed domains, analytics, discovery, appearance, and action policy do not need to be copied into the DOM. The current Workspace values are fetched after bootstrap.
Advanced boot configuration
The inline rover('boot', config) form is for applications that intentionally manage runtime overrides in code. A value supplied here takes precedence over the matching saved runtime value for that page load. Keep the override small so Workspace remains the clear source of truth.
window.rover?.('boot', {
siteId: 'YOUR_SITE_ID',
publicKey: 'pk_site_YOUR_PUBLIC_KEY',
siteKeyId: 'YOUR_SITE_KEY_ID',
apiBase: 'https://agent.rtrvr.ai',
openOnInit: false,
sessionScope: 'shared_site',
ui: {
agent: { name: 'Rover' },
},
});Identity and startup
| Option | Type | Use |
|---|---|---|
siteId | string | Required site identifier from Workspace. |
publicKey | string | Public pk_site_* browser credential from Workspace. |
siteKeyId | string | Active site-key identifier from the generated snippet. |
apiBase | string | Advanced API-base override. The normal value is https://agent.rtrvr.ai. |
presentationMode | 'visible' | 'invisible' | Show Rover's visitor UI or run without visible presentation. |
sessionScope | 'shared_site' | 'tab' | Share one site session across tabs or isolate each tab. |
mode | 'full' | 'safe' | Use full runtime behavior or constrained execution. |
openOnInit | boolean | Open Rover after boot. Default is false. |
workerUrl | string | Custom worker URL for self-hosting or strict CSP environments. |
Do not put secrets in browser config
publicKey is designed for the browser. Webhook secrets, server-action secrets, configuration-connection keys, auth tokens, and session tokens are not. Rover's backend mints and manages runtime auth material; page code should not supply it.Page and navigation behavior
| Option | Type | Use |
|---|---|---|
allowedDomains | string[] | Optional page-level override for allowed hosts. Prefer the domain list in Install. |
domainScopeMode | 'registrable_domain' | 'host_only' | Controls whether plain domain entries include subdomains or match only the exact host. |
allowActions | boolean | Set false for a read-only browser session. |
deepLink | { enabled?, consume? } | Enable fixed rover, rover_shortcut, and rover_playbook URL launches. |
pageConfig | RoverPageCaptureConfig | Advanced page-capture and scroll behavior. |
disableFrameBridge | boolean | Disable the same-party cross-origin frame bridge. |
Rover keeps same-host work in the current tab unless the page asks for a new one. Outside-scope navigation opens with notice. Domain matching details live in Security & Policies.
Live visitor identity
| Option | Type | Use |
|---|---|---|
identity | RoverIdentityInput | Initial user or account identity when it is already known at boot. |
identityProvider | () => identity | Async identity lookup. Built-in adapters cover Segment, PostHog, Amplitude, and Google Analytics. |
visitor | { name?, email?, contextToken?, context? } | Bounded display and experience context. Never include secrets or payment data. |
visitorId | string | Optional analytics correlation hint. It is not identity or authorization. |
// Call after your own sign-in state resolves.
window.rover?.identify({
userId: user.id,
accountId: user.accountId,
traits: { plan: user.plan, role: user.role },
name: user.preferredName,
});
// Clear both site context and Rover continuity on sign-out.
window.rover?.update({ visitor: null });
window.rover?.resetIdentity();Use rover.group(...) when an identified user belongs to an account. See Audience & Identity for provider examples, verified context, memory, and privacy rules.
Visitor UI overrides
| Option | Nested fields |
|---|---|
ui.agent | name |
ui.mascot | disabled, imageUrl, mp4Url, webmUrl, soundEnabled, shape |
ui.shortcuts | A bounded array of RoverShortcut entries. |
ui.experience | Presence, shell, stream, inputs, audio, motion, and theme overrides. |
ui.greeting | text, delay, duration, disabled |
ui.voice | Voice-input defaults including enabled state, language, and auto-stop timing. |
ui.panel | resizable |
ui.tabIndicator | titlePrefix, faviconBadge, widgetTabBar |
ui.muted | Initial mascot mute state when mascot sound is enabled. |
ui.thoughtStyle | 'concise_cards' | 'minimal' |
ui.showTaskControls | Show or hide task lifecycle controls. |
Prefer Workspace Appearance for values an owner should be able to change without a deploy. Use these fields when the host application must decide them at runtime.
Actions, analytics, and external context
| Option | Use |
|---|---|
tools.client | Client tool definitions registered by application code. |
tools.web | External text-context settings: enablement, allowlist, denylist, and on-demand scraping mode. |
cloudSandboxEnabled | Allow entitled cloud tools to read or act on approved third-party sites. |
analytics | Runtime collection, consent, batching, WebMCP, memory, interview, and experiment overrides. Prefer Analytics settings in Workspace. |
telemetry | Operational event sampling and batching. Payload details stay off by default. |
agentDiscovery | Runtime discovery-surface override. Prefer Install for the saved owner policy. |
identitySync | Opt out of the default pairwise identity sync or override its API base. |
Advanced runtime controls
The SDK also accepts the following operational groups. Most sites should leave them unset and use Rover's tested defaults.
| Option | Controls |
|---|---|
taskRouting | ACT, planner, or automatic routing and planner fallback. |
tabPolicy | Observer preference and action-lease timing. |
timing | Navigation delay, action timeout, DOM settle, and sparse-tree retry timing. |
transport | On-demand worker activation and idle close timing. |
task | Crash resume, ask-user timeout, follow-up hints, concurrency, queue, and archive bounds. |
chat | In-run chat behavior and deterministic resume cues. |
external | External intent selection, confirmation, and adversarial gate. |
taskContext | Advisory reset and follow-up similarity hints. |
checkpointing | Cloud checkpoint timing, TTL, and state/error callbacks. |
stability | Persisted-state and snapshot byte limits. |
apiMode and apiToolsConfig | Advanced cloud API-mode and additional tool exposure. |
Internal fields are not integration options
authToken, sessionToken, sessionTokenExpiresAt, features, cloudHosted, and cloudHostedPreview exist for Rover-managed runtime handoffs. Do not set them in a site integration.Runtime methods
| Method | Purpose |
|---|---|
boot(config) / init(config) | Start Rover. init is a compatibility alias. |
update(config) | Change runtime fields without a full reboot. |
shutdown() | Stop Rover and release its page resources. |
open() / close() | Open or close the Rover panel. |
show() / hide() | Show or hide Rover's presence. |
send(text) / ask(text, options) | Start a visitor task or open Rover with a request. |
sendFeedback(text) | Steer the current active run without starting a new task. |
newTask() / endTask() | Control the current task boundary. |
identify() / group() / resetIdentity() | Update user and account identity or return to anonymous continuity. |
registerTool() | Register a browser action handler. The returned function unregisters it. |
registerPromptContextProvider() | Provide bounded current-page context for a request. |
createWorkbench() | Create a host-owned Rover workbench with scoped context and tools. |
trackGoal() / trackEvent() / trackConversion() | Send registered business and product outcomes to Rover Analytics. |
setConsent() | Apply or revoke analytics consent. |
on(event, handler) | Subscribe to lifecycle, task, identity, analytics, and diagnostic events. |
getState() / getAgentCard() | Read the current runtime snapshot or resolved agent card. |
requestSigned() | Make a signed request using the active Rover session. |
For A2W runs, Connect AI REST/MCP, request envelopes, streaming, and continuation input, use the API Reference. These are server contracts, not boot configuration.