Install the Mascotbot Lipsync SDK

The SDK is published to npm.mascot.bot, a private registry — it is not on npmjs.com. You need a Mascotbot API key to install and to run.

1. Get an API key

Create a key at app.mascot.bot/api-keys. Keys are prefixed by environment:

Prefix	Where it works	Metering
`mascot_dev_…`	`localhost`, `*.localhost`, `127.0.0.1`, private networks only	Development meters — no billing, tamper-tolerant
`mascot_pub_…`	Your registered public domains	Production meters — tamper detection active

A mascot_dev_… key sent from a public origin is rejected by design, and a mascot_pub_… key from localhost is rejected too. Use the matching key for the environment. See Licensing & keys for the full model.

2. Point npm at the private registry

Add a .npmrc at the root of your project:

@mascotbot:registry=https://npm.mascot.bot/
//npm.mascot.bot/:_authToken=mascot_xxx

Never commit .npmrc with the auth token. Add it to .gitignore and inject the token from a CI secret / environment variable instead.

3. Install the package

pnpm add @mascotbot/react

pnpm add @mascotbot/core

pnpm add @rive-app/react-webgl2 @rive-app/webgl2

@rive-app/webgl2 (and @rive-app/react-webgl2 for React) is an optional peer dependency of the /rive subpaths. Install it only if you render an avatar; the audio pipeline alone does not need it. npm and yarn work the same way once the registry line is in .npmrc.

4. Configure the client

Pass configuration to <MascotProvider> (React) or LipsyncClient.init (vanilla):

Option	Type	Default	Notes
`apiKey`	`string`	required	`mascot_dev_…` (localhost) or `mascot_pub_…` (production)
`userId`	`string`	random	Stable per-user id for MAU billing attribution
`licenseEndpoint`	`string`	`https://license.mascot.bot`	Override only if Mascotbot points you elsewhere
`devMode`	`boolean`	auto-detect	Forced on for `localhost`, `*.localhost`, `127.0.0.1`, private IPs. Skips the Origin allow-list and routes events to dev meters.
`fingerprintHash`	`string`	hashed UA + hardware	Override to control session attribution

"use client";
import { MascotProvider } from "@mascotbot/react";

export default function Layout({ children }: { children: React.ReactNode }) {
  return <MascotProvider apiKey={process.env.NEXT_PUBLIC_MASCOT_KEY!}>{children}</MascotProvider>;
}

Production publishable keys (mascot_pub_…) are safe in client bundles — they are scoped to your allow-listed origins. Keep standing third-party keys (TTS, OpenAI, ElevenLabs) on the server.

TypeScript

All packages ship .d.ts. Public types are re-exported from each root entry point — you do not need to install lipsync-core separately just for types if you depend on lipsync-react.

Quickstart

A working avatar in a few lines.

Licensing & keys

Dev vs production, session lifecycle, error codes.

Getting Started

Core concepts

React SDK

Core SDK (vanilla)

Realtime providers

Reference

Ready-made Mascots

Install the Mascotbot Lipsync SDK - Private Registry & API Keys

1. Get an API key

2. Point npm at the private registry

3. Install the package

4. Configure the client

TypeScript

Next

Quickstart

Licensing & keys

​1. Get an API key

​2. Point npm at the private registry

​3. Install the package

​4. Configure the client

​TypeScript

​Next

Quickstart

Licensing & keys

1. Get an API key

2. Point npm at the private registry

3. Install the package

4. Configure the client

TypeScript

Next