Operator reference

Website Widget

Deploy the Nexus chat widget on your website

Before you begin

This reference describes the underlying platform. Use a Nexus school release with its school membership, class policy, and cost controls. Installing a base engine alone does not add those controls.

The Nexus Website Widget allows you to embed AI-powered chat directly on any website.

Features include:

Lightweight ~100-150kb gzipped bundle
Fully customizable colors and branding
Responsive design (desktop popup, mobile fullscreen)
Real-time streaming responses via SSE
Session persistence across page reloads

Deployment Options#

Cloud Deployment (Recommended)#

A hosted Nexus widget distribution has not been confirmed. The code below is a deployment reference for operators who build and configure a widget. Do not paste an administrator API key into a public website.

<!-- Load the widget -->
<script type="module" src="https://cdn.onyx.app/widget/1.1/dist/onyx-widget.js"></script>

<!-- Configure and display -->
<onyx-chat-widget
backend-url="https://school.narb.cc/api"
api-key="your_api_key_here"
mode="launcher"
> </onyx-chat-widget>

Self-Hosted Deployment#

For self-hosted Nexus instances, you'll need to build and host the widget yourself.

Clone the repository#

Clone the Nexus repository from GitHub.

  cd widget/

Install dependencies#

  npm install

Navigate to your Onyx admin panel and create a new API key specifically for the widget.

Create a limited-scope API key with only chat permissions. Never use admin or full-access keys since the API key will be visible in client-side code.

Configure environment (optional)#

For builds with baked-in configuration, create a .env file:

  cp .env.example .env

Edit .env and set your backend URL and API key:

  VITE_WIDGET_BACKEND_URL=https://your-backend.com
  VITE_WIDGET_API_KEY=your_api_key

For cloud-style deployment (config via HTML attributes):

  npm run build:cloud

For self-hosted deployment (config baked into bundle):

  npm run build:self-hosted

Deploy the bundle#

Upload dist/onyx-widget.js to your CDN or web server.

Customer Embed Code#

After deployment, provide customers with the embed code:

Cloud-style (attributes required):

<script type="module" src="https://your-cdn.com/onyx-widget.js"></script>
<onyx-chat-widget
backend-url="https://your-backend.com"
api-key="customer_api_key"
agent-name="Support"
logo="https://path-to-your-logo.com/"
> </onyx-chat-widget>

Self-hosted (config baked in):

<script type="module" src="https://your-cdn.com/onyx-widget.js"></script>
<onyx-chat-widget
agent-name="Support"
logo="https://path-to-your-logo.com/"
> </onyx-chat-widget>

Configuration Reference#

Required Attributes#

Attribute	Type	Description
`backend-url`	string	Your Onyx backend API URL
`api-key`	string	API key for authentication

`backend-url`#

The URL of your Onyx backend API. This is where the widget sends chat requests.

Onyx Cloud: Use https://school.narb.cc or your tenant-specific URL
Self-hosted: Use your Onyx instance URL (e.g., https://onyx.yourcompany.com)

<!-- a managed deployment -->
<onyx-chat-widget backend-url="https://school.narb.cc/api" ...></onyx-chat-widget>

<!-- Self-hosted -->
<onyx-chat-widget backend-url="https://onyx.yourcompany.com" ...></onyx-chat-widget>

`api-key`#

A valid Onyx API key for authenticating widget requests. This key is visible in client-side code, so always use a limited-scope key.

<onyx-chat-widget
backend-url="https://school.narb.cc/api"
api-key="on_abc123xyz789"
...
></onyx-chat-widget>

For self-hosted builds with baked-in config, backend-url and api-key can be set via environment variables during build instead of HTML attributes.

Optional Attributes#

Attribute	Type	Default	Description
`agent-id`	number	`undefined`	Specific agent/persona to use
`agent-name`	string	`"Assistant"`	Display name in header
`logo`	string	Onyx logo	URL to custom logo image
`primary-color`	string	`#1c1c1c`	Primary brand color (buttons, accents)
`background-color`	string	`#e9e9e9`	Widget background color
`text-color`	string	`#000000bf`	Text color (75% opacity black)
`mode`	string	`"launcher"`	Display mode: `"launcher"` or `"inline"`
`include-citations`	boolean	`false`	Show citation badges linking to source documents

`include-citations`#

When enabled, assistant messages display clickable citation badges below the response text. Each badge shows a sequential number and the source document title, linking directly to the original document.

<onyx-chat-widget
backend-url="https://school.narb.cc/api"
api-key="on_abc123"
include-citations="true"
> </onyx-chat-widget>

Be mindful of document access when enabling citations. The widget will cite any documents accessible to the configured agent or API key. If the agent has access to private or internal documents, citation links may point to resources that end users do not have permission to view.

To avoid exposing private document links, either scope the agent's document access to only public-facing sources, or disable citations for public-facing widget deployments.