> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Options

> Configure Moss behavior through AgentProvider config

## Overview

SDK configuration options allow you to customize Moss behavior directly in your application code. These settings **override Dashboard defaults** when specified, giving developers fine-grained control per deployment, environment, or user segment.

<Info>
  **Priority reminder:** SDK configuration options take precedence over
  Dashboard settings. When you configure an option in code, it will override
  the value set in the Dashboard. This allows developers to customize behavior
  per-deployment while using Dashboard settings as defaults.
</Info>

***

## Required Options

These options must be provided in the `AgentProvider` config:

```tsx theme={null}
import { AgentProvider, AssistantButton } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
}}>
  <AssistantButton />
</AgentProvider>
```

| Option          | Type                    | Description                                   |
| --------------- | ----------------------- | --------------------------------------------- |
| `apiUrl`        | `string`                | Moss API endpoint URL                         |
| `applicationId` | `string`                | Your unique application ID from the Dashboard |
| `userId`        | `string`                | Unique identifier for the current user        |
| `getJwt`        | `() => Promise<string>` | Function that returns a JWT token             |

<Warning>
  The `userId` should be a stable identifier for your user. Avoid using PII
  (email, name) directly - use a hashed or anonymized identifier instead.
</Warning>

***

## Common Options

These options are frequently used to customize SDK behavior:

### Language

Set the UI language for the SDK interface.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  language: 'en',  // 'en', 'ko', or undefined for auto-detect
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `undefined` (auto-detects browser language)

<Tip>
  Leave undefined to automatically use the user's browser language preference.
</Tip>

### Vision

Enable or disable screenshot analysis capabilities.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  useVision: true,  // Enable visual context
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `true` (from Dashboard)

### Session Recording

Control whether user sessions are recorded for replay.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableSessionRecording: false,  // Disable for privacy-sensitive users
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `true` (from Dashboard)

### Screen History

Include user action history in AI context.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableScreenHistoryRecording: true,
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `true` (from Dashboard)

***

## Appearance

Customize the visual theme of the Moss assistant UI.

### Using Presets

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: 'blue',  // Use a preset theme
}}>
  <AssistantButton />
</AgentProvider>
```

**Available presets:**

| Preset     | Description                                   |
| ---------- | --------------------------------------------- |
| `'blue'`   | Default blue theme with glassmorphism effects |
| `'purple'` | Purple theme with solid backgrounds           |

### Custom Appearance

Override specific properties by passing a partial object:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: {
    colors: {
      primary: '#3b82f6',
      primaryLight: '#60a5fa',
    },
    modal: {
      defaultPosition: { right: 20, bottom: 20 },
      defaultSize: { width: 400, height: 600 },
    },
    effects: {
      glassmorphism: true,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>
```

### Customizable Properties

| Category      | Properties                                                                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `colors`      | `primary`, `primaryLight`, `primaryLighter`, `userMessage`, `assistantMessage`, `headerBackground`, `inputAreaBackground`, `modalBackground`, `text.*`, `border`, `success`, `error` |
| `typography`  | `fontFamily`, `fontSize.*`, `lineHeight.*`                                                                                                                                           |
| `spacing`     | `3xs`, `2xs`, `xs`, `sm`, `md`, etc.                                                                                                                                                 |
| `radius`      | `sm`, `md`, `lg`, `xl`                                                                                                                                                               |
| `shadows`     | `sm`, `md`, `lg`                                                                                                                                                                     |
| `effects`     | `glassmorphism`, `glassBlur`, `glassOpacity`                                                                                                                                         |
| `inputBar`    | `roundedTop`, `topShadow`                                                                                                                                                            |
| `progressBar` | `height`                                                                                                                                                                             |
| `modal`       | `defaultPosition`, `defaultSize`                                                                                                                                                     |

<Tip>
  Partial objects are deep-merged with the base theme. You only need to specify the properties you want to override.
</Tip>

***

## Session Options

Configure session management behavior:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  sessionConfig: {
    inactivityTimeout: 60,
    maxSessionAge: 4,
    showNotification: true,
  },
}}>
  <AssistantButton />
</AgentProvider>
```

| Option              | Type      | Default | Description                                  |
| ------------------- | --------- | ------- | -------------------------------------------- |
| `inactivityTimeout` | `number`  | `30`    | Minutes of inactivity before session expires |
| `maxSessionAge`     | `number`  | `2`     | Maximum session duration in hours            |
| `showNotification`  | `boolean` | `true`  | Show notification on new session             |

***

## Developer Options

Advanced settings for debugging and customization:

### Screenshot Mode

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  screenshotMode: 'viewport',  // 'fullpage' or 'viewport'
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `'fullpage'`

| Value      | Description                         |
| ---------- | ----------------------------------- |
| `fullpage` | Captures the entire scrollable page |
| `viewport` | Captures only the visible portion   |

<Tip>
  Use `viewport` for apps with very long pages to reduce processing time.
</Tip>

### Log Level

```tsx theme={null}
import { AgentProvider, AssistantButton, LogLevel } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  logLevel: LogLevel.DEBUG,  // DEBUG, INFO, WARN, ERROR, SILENT
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `LogLevel.INFO`

`logLevel` takes the `LogLevel` enum exported by the SDK, not a string. Each level includes everything more severe than itself (`DEBUG` shows everything, `SILENT` disables logging).

### Debug Mode

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  debugMode: true,
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `false`

Enables verbose logging and debug features for troubleshooting.

### DOM Target Selector

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  observeTargetSelector: '#main-content',
}}>
  <AssistantButton />
</AgentProvider>
```

**Default:** `'body'`

CSS selector for the DOM element to observe. Change this to limit observation to a specific part of your page.

### DOM Stability

Configure how the SDK waits for the page to stabilize:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  stability: {
    maxTotalWaitMs: 15000,
    layers: {
      networkIdle: true,
      domMutations: true,
      loadingIndicators: false,
      frameReadiness: true,
      resourceQuiet: true,
      layoutShift: false,
      browserIdle: true,
      finalFrame: true,
    },
    domMutations: {
      quietPeriodMs: 1000,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>
```

<Tip>
  See the [SDK Advanced Configuration](/en/sdk/advanced#stability-tuning)
  guide for detailed layer-by-layer documentation.
</Tip>

***

## Complete TypeScript Interface

Here's the full TypeScript interface for SDK configuration:

```typescript theme={null}
interface MossConfig {
  // Required
  apiUrl: string;
  applicationId: string;
  userId: string;
  getJwt: () => Promise<string>;

  // Application Features
  useVision?: boolean;
  language?: 'en' | 'ko';
  appearance?: AppearanceInput;  // 'blue' | 'purple' | custom object

  // Recording & History
  enableSessionRecording?: boolean;
  enableScreenHistoryRecording?: boolean;

  // Session Management
  sessionConfig?: {
    inactivityTimeout?: number;
    maxSessionAge?: number;
    showNotification?: boolean;
  };

  // Technical Settings
  logLevel?: LogLevel;  // enum: DEBUG, INFO, WARN, ERROR, SILENT
  debugMode?: boolean;
  screenshotMode?: 'fullpage' | 'viewport';
  observeTargetSelector?: string;

  // DOM Stability
  stability?: {
    maxTotalWaitMs?: number;
    layers?: {
      networkIdle?: boolean;
      domMutations?: boolean;
      loadingIndicators?: boolean;
      frameReadiness?: boolean;
      resourceQuiet?: boolean;
      layoutShift?: boolean;
      browserIdle?: boolean;
      finalFrame?: boolean;
    };
    domMutations?: {
      quietPeriodMs?: number;
    };
  };
}
```

***

## Settings Not Available in SDK

The following settings can only be configured through the Dashboard:

* **AI Assistant Instructions** - Custom instructions for the AI
* **API Keys** - Authentication credentials
* **Domain Access Control** - Allowed domains list
* **Vector Store Configuration** - RAG system settings

<Warning>
  These settings are Dashboard-only for security reasons. They affect
  application-wide behavior and authentication.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="lightbulb" href="/en/configurations/examples">
    See complete configuration examples for different use cases
  </Card>

  <Card title="Dashboard Settings" icon="browser" href="/en/configurations/dashboard-settings">
    Configure application defaults in the Dashboard
  </Card>
</CardGroup>