The Runbear React SDK (@runbear-io/react) lets you embed a Runbear AI agent as a chat widget directly in your own web app. It renders a complete, styled chat UI — message history, streaming responses, file attachments, suggested questions — and talks to the same Runbear /v1 API documented in the Runbear API Docs. (File attachments and suggested questions are unavailable in session mode; see Authentication & Security.)

<aside> 💡

The SDK is the fastest way to add Runbear to a website. If you only need raw request/response access (server-to-server, non-React, or a fully custom UI), use the Runbear API Docs directly instead.

</aside>

Overview

Key ideas

• One widget = one agent. You bind an assistantId when you create the client, so a single embedded widget always talks to one specific agent.
• Batteries included. The SDK ships its own UI and styles. You give it a DOM element to mount into; it manages everything inside.
• Threads are conversations. Each chat session maps to a Runbear thread. You can capture the thread ID to persist and later resume a conversation.

Requirements: a modern React app (React 18+; the SDK is built and tested against React 19).

Installation

The SDK is published to GitHub Packages (private registry), so installing it requires a GitHub Personal Access Token (PAT).

1. Create a GitHub Personal Access Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Click Generate new token (classic).
3. Select only the read:packages scope.
4. Copy the generated token.

2. Configure .npmrc

Create or edit .npmrc in your project root:

@runbear-io:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE

<aside> ⚠️

Don't commit your token. Add .npmrc to .gitignore, or reference an environment variable instead: //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

</aside>