Configuration

All configuration is passed to KiBeeClient at construction time. None of the options require a server restart — you can swap renderers, update the API URL, or change credentials without re-deploying your app.

KiBeeClient options

Option	Type	Required	Description
`renderer`	`BeeRenderer`	Yes	The renderer that draws the bee. Use `ThreeBeeRenderer` from `@kibee/renderer-three`.
`apiBaseUrl`	`string`	Yes	Base URL of your KiBee API, e.g. `https://api.kibee.ai`.
`websiteId`	`string`	Recommended	Your workspace public ID (starts with `kb_ws_`). Required for publishable-key auth.
`publicKey`	`string`	Recommended	Publishable API key (starts with `kb_pub_`). Safe to embed in browser code.
`locale`	`string`	No	BCP 47 locale for bee speech (default: `"en"`).

ThreeBeeRenderer options

Option	Type	Default	Description
`dockPosition`	`string`	`"bottom-right"`	Where the bee docks when idle. One of `bottom-right`, `bottom-left`, `top-right`, `top-left`.
`dockSize`	`number`	`58`	Diameter of the dock button in pixels.
`dockVariant`	`string`	`"hive"`	Visual style of the dock. `"hive"` or `"circle"`.
`dockEnabled`	`boolean`	`true`	Show the dock button. Set `false` for fully programmatic control.
`qualityTier`	`string`	`"auto"`	`"auto"` detects device capability. Override with `"low"`, `"medium"`, or `"high"`.
`enableShadows`	`boolean`	`false`	Render drop shadows under the bee. Disable on low-end devices.
`motionMode`	`string`	`"auto"`	`"auto"` respects `prefers-reduced-motion`. Use `"full"` or `"minimal"` to override.
`assetUrl`	`string`	`"/models/bee-runtime.glb"`	Path to the bee 3D asset. Override when self-hosting or using a CDN.

Full example

TypeScript

import { KiBeeClient } from "@kibee/sdk";
import { ThreeBeeRenderer } from "@kibee/renderer-three";

const kibee = new KiBeeClient({
  websiteId: process.env.NEXT_PUBLIC_KIBEE_WEBSITE_ID,
  publicKey: process.env.NEXT_PUBLIC_KIBEE_PUBLIC_KEY,
  apiBaseUrl: process.env.NEXT_PUBLIC_KIBEE_API_BASE ?? "https://api.kibee.ai",
  renderer: new ThreeBeeRenderer({
    assetUrl: "/models/bee-runtime.glb",
    dockPosition: "bottom-right",
    dockSize: 58,
    dockVariant: "hive",
    dockEnabled: true,
    qualityTier: "auto",
    enableShadows: false,
    motionMode: "auto",
  }),
});

await kibee.init();

Environment variables

Store credentials in environment variables. Both websiteId and publicKey are safe to expose in browser bundles — they are publishable credentials, not secret keys.

.env.local

NEXT_PUBLIC_KIBEE_WEBSITE_ID=kb_ws_your_workspace
NEXT_PUBLIC_KIBEE_PUBLIC_KEY=kb_pub_live_your_key
NEXT_PUBLIC_KIBEE_API_BASE=https://api.kibee.ai

Never expose your secret API key in browser code. Use the publishable key (kb_pub_) for the browser SDK. Secret keys are for server-to-server calls only.