@rnsk/bot
Embeddable Runstack chat widget — gooey UI, API-key auth, whitelabel branding, and optional Studio agent or toolkit scoping.
Source: https://runstack.engineer/docs/rnsk-bot
@rnsk/bot is a React chat widget you embed in any site or app. It ships with a collapsible gooey UI, streaming messages, tool-call UI, and OAuth connect flows — so you do not have to build chat screens from scratch.
The widget authenticates with your Runstack API key (rnsk_…) and talks to dedicated bot endpoints on the Runstack server. Tool execution, OAuth, and secrets stay on Runstack's side — the same execution layer as MCP and @rnsk/tools.
Install
Install the package and its peer dependencies (they are not bundled):
npm install @rnsk/bot react react-dom ai @ai-sdk/react| Package | Supported range |
|---|---|
react | ^18.0.0 or ^19.0.0 |
react-dom | ^18.0.0 or ^19.0.0 |
ai | ^4.0.0, ^5.0.0, ^6.0.0, or ^7.0.0 |
@ai-sdk/react | ^1.0.0, ^2.0.0, ^3.0.0, or ^4.0.0 |
Import the widget stylesheet in your app entry (for example main.tsx):
Tailwind CSS v4
If your app uses Tailwind CSS v4, add a @source entry so Tailwind scans the published widget bundle for any utility classes used inside @rnsk/bot:
@source "../node_modules/@rnsk/bot/dist/**/*.js";Add that line to your global CSS file (alongside other @source directives), typically next to your @import "tailwindcss"; block. Adjust the path if your node_modules folder is not one level above src/.
The widget ships most styles in bot.css, so this @source line is only needed when Tailwind must see classes referenced from the compiled dist/ output.
Basic usage
return (
> An interactive demo is available in the web docs.
)
}Do not expose long-lived API keys in public client bundles. For production, proxy requests through your backend or restrict keys to low-risk scopes.
Widget behavior
The bot follows a three-state interaction flow:
- Collapsed — a small branded logo button anchored to the bottom-left or bottom-right corner.
- Input expanded — clicking the logo expands a gooey input bar with your placeholder text and a send button.
- Chat open — sending a message opens a chat panel above the input bar (gooey stack). Clicking the logo again collapses the widget.
Props
| Prop | Type | Default | Description | ||
|---|---|---|---|---|---|
apiKey | string | required | Runstack API key (rnsk_…) | ||
position | "left" \ | "right" | "right" | Fixed corner anchor | |
placeholder | string | "Ask anything…" | Input placeholder text | ||
agentIds | string[] | — | Scope tools to one or more Studio agents | ||
toolkits | string[] | — | Scope tools to toolkit ids (same as @rnsk/tools) | ||
systemPrompt | string | — | Extra system instructions appended on the server | ||
apiBase | string | https://app.runstack.engineer | Runstack API base URL | ||
theme | "light" \ | "dark" \ | "system" | "system" | Widget color theme |
Scope to toolkits
Limit tool discovery to specific products by passing toolkit ids (same field as @rnsk/toolkits manifests):
> An interactive demo is available in the web docs.Find ids on each toolkit docs page — for example web-search, google-calendar.
Scope to Studio agents
Bind the bot to one or more Studio agents by id. The server scopes tools to the agent's workflow and applies its role as system instructions:
> An interactive demo is available in the web docs.You can combine agentIds and toolkits. When both are set, the effective scope is the union of toolkit ids from the agents plus any explicit toolkits you pass.
Model selection
The bot does not accept LLM provider credentials as props. Instead, configure the model in your workspace:
- Go to Settings → Workspace → LLM Providers
- Set Bot model to the model you want embedded widgets to use
Resolution order on the server:
- Workspace Bot model (if set)
- Workspace default chat model (if set)
- Runstack auto-default (Cloudflare / OpenRouter)
Bring-your-own-key providers configured in LLM settings are used automatically when selected.
Whitelabel branding
Branding is tied to the workspace bound to your API key. On mount, the widget fetches GET /api/bot/config and applies your whitelabel logo to the trigger button.
Configure branding under Settings → Workspace → Whitelabel — company name, logo, font, and colors. No extra props are required on the component.
Theme
Pass theme="system" (default) to follow the user's prefers-color-scheme preference, or pin "light" / "dark". Theme styles are scoped to the widget root and do not affect the rest of your page.
When to use it
- You want a product-embedded assistant quickly.
- You already use Runstack toolkits and need connect + execute UX in the browser.
- You publish agents in Studio and want that persona on your site or dashboard.
For headless agents (no UI), use @rnsk/tools with the AI SDK instead.