@moss-tools/founding-agent

Embeddable voice founding agent for Moss-powered company websites. Drop the React component onto any page and your visitors can talk to a voice agent powered by your Q&A knowledge base.

• Server helper for minting LiveKit session tokens from your backend.
• React component that renders the voice UI and connects to LiveKit on click.
• Works with Next.js, Remix, Vite, or any React setup.

Install

npm install @moss-tools/founding-agent
# required peers for the React component
npm install react react-dom tslib @livekit/components-react @livekit/components-styles livekit-client motion lucide-react zustand

Server-only usage (no React) has zero runtime dependencies — Node 18+ fetch is all it needs.

Environment

You get two credentials from the Moss dashboard when you create a founding agent:

• MOSS_FA_API_KEY — server-only. Keep this in a backend env var (e.g. Vercel Environment Variables). Starts with sk_.
• MOSS_FA_PUBLISHABLE_KEY — safe to ship to the browser. Passed to the React component. Starts with pk_.

1. Backend: mint a session token

The React component POSTs to a token endpoint you provide. That endpoint calls the Moss service with your server-only API key and returns the LiveKit token to the browser. A Next.js App Router example:

// app/api/moss-token/route.ts
import { createFoundingAgentSession } from "@moss-tools/founding-agent";

export async function POST() {
  const session = await createFoundingAgentSession({
    apiKey: process.env.MOSS_FA_API_KEY!,
  });
  return Response.json(session);
}

createFoundingAgentSession returns { token, serverUrl, roomName }.

For more control (custom error handling, reusing the client) use the class form:

import { MossFoundingAgent } from "@moss-tools/founding-agent";

const agent = new MossFoundingAgent({
  apiKey: process.env.MOSS_FA_API_KEY!,
  timeoutMs: 10_000, // optional
});

export async function POST() {
  const session = await agent.createSession();
  return Response.json(session);
}

2. Frontend: drop in the component

Wrap your page (or app) once with MossFoundingAgentProvider — it fetches the public config (name, greeting, suggested prompts) and wires the token endpoint — then render MossFoundingAgentCard anywhere inside.

"use client";

import {
  MossFoundingAgentCard,
  MossFoundingAgentProvider,
} from "@moss-tools/founding-agent/react";

export default function LandingPage() {
  return (
    <MossFoundingAgentProvider
      publishableKey={process.env.NEXT_PUBLIC_MOSS_FA_PUBLISHABLE_KEY!}
    >
      <main>
        <h1>Talk to our team</h1>
        <MossFoundingAgentCard />
      </main>
    </MossFoundingAgentProvider>
  );
}

That's the minimum. The card:

1. Reads the public config from the provider (name, suggested prompts).
2. Renders the aura orb + "Start Conversation" button.
3. On click, POSTs to /api/moss-token to get a session token.
4. Connects to LiveKit and swaps to the connected UI (transcript, mute, end).

Tailwind setup

The card uses Tailwind utility classes internally. If your app is on Tailwind v4, point its CSS at the package's compiled output so the utilities get picked up:

/* globals.css */
@import "tailwindcss";
@source "../node_modules/@moss-tools/founding-agent/dist/**/*.{js,mjs}";

Props

<MossFoundingAgentProvider>

| Prop | Type | Default | Description | |------|------|---------|-------------| | publishableKey | string | — | Required. The pk_... key for this agent. | | tokenEndpoint | string | /api/moss-token | URL of your backend route that returns { token, serverUrl }. | | onError | (error: Error) => void | — | Fires on config fetch errors. |

<MossFoundingAgentCard>

Accepts all <div> props, plus:

| Prop | Type | Default | Description | |------|------|---------|-------------| | label | string | Agent name from config | Header label. | | suggestedPrompts | string[] | Q&A questions from config | Rotating "Try asking" chips. | | color | `#${string}` | #7200E1 | Aura orb color. | | themeMode | "dark" \| "light" | "light" | Forces the aura shader theme. |

Security model

• The API key is never exposed to the browser. The component only ever sees the publishable key and the short-lived LiveKit token returned by your backend.
• LiveKit tokens are minted server-side by the Moss service with minimal grants (audio publish/subscribe only, no data channel, no room create).
• Room names are chosen by the service (fa-{slug}-{timestamp}). The browser never proposes a room name.

License

MIT