Getting started

Add the chat sidebar to a React or JavaScript application. If you haven't created an agent or connected your backend yet, start with the Quickstart.

Before mounting

Add an authenticated token endpoint at /api/astralbeam/token, then install the SDK:

npm
npm install @astralbeam/sdk

For an app without a bundler, use a script tag.

Mount the widget

Give the container a definite height:

React
import { AstralBeamChat } from "@astralbeam/sdk/react"

export function Assistant() {
  return (
    <aside style={{ height: "100dvh" }}>
      <AstralBeamChat />
    </aside>
  )
}

Sign in to your application and send "Say hello in one sentence." A reply should stream into chat. For self-hosting, set apiUrl to your deployment's /api base. See SDK props for customization.

Layout

  • In a flex column, use flex: 1 and min-height: 0 on the container so it can shrink and scroll.
  • Mount above your router if the transcript should survive page navigation.
  • Add safe-area padding to your container for devices with a notch.

Next

Add tools and widgets, customize SDK props, or build your own UI with Headless. Read the security model before exposing application actions.

A complete TanStack Start example

Linearity shows a persistent sidebar, server token route, and host tools in a project tracker.

NOTE: Its shared password and selectable identities are for a demo. Derive production identities from your authenticated session. Never expose an API key through a VITE_ variable.