Getting Started

Installation


npm install @guidekit/core @guidekit/react @guidekit/server

For voice support, also install the VAD package:


npm install @guidekit/vad

Setup with CLI

The fastest way to get started:


npx @guidekit/cli init

This scaffolds the token endpoint, provider component, and environment variables for your framework (Next.js App Router, Pages Router, or generic React).

Then generate a signing secret:


npx @guidekit/cli generate-secret

Add the secret and your API keys to .env.local:


GUIDEKIT_SECRET=your-generated-secret
LLM_API_KEY=your-llm-api-key
STT_API_KEY=your-stt-api-key        # Optional, for voice
TTS_API_KEY=your-tts-api-key        # Optional, for voice

Manual Setup

1. Create Token Endpoint


// app/api/guidekit/token/route.ts (Next.js App Router)
import { createSessionToken } from '@guidekit/server';
 
export async function POST() {
  const token = await createSessionToken({
    signingSecret: process.env.GUIDEKIT_SECRET!,
    llmApiKey: process.env.LLM_API_KEY!,
    sttApiKey: process.env.STT_API_KEY,
    ttsApiKey: process.env.TTS_API_KEY,
    expiresIn: '15m',
  });
  return Response.json(token);
}

2. Add the Provider


'use client';
// app/layout.tsx
import { GuideKitProvider } from '@guidekit/react';
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <GuideKitProvider
      tokenEndpoint="/api/guidekit/token"
      agent={{
        name: 'Guide',
        greeting: 'Hi! How can I help you today?',
      }}
      options={{
        mode: 'text',
        debug: process.env.NODE_ENV === 'development',
      }}
    >
      {children}
    </GuideKitProvider>
  );
}

3. Verify Setup


npx @guidekit/cli doctor

This checks your environment variables, package installations, and provider connectivity.

Quick Prototyping (Dev Only)

For quick prototyping without a token endpoint, pass API keys directly:


<GuideKitProvider
  llm={{ provider: 'gemini', apiKey: 'your-key' }}
  agent={{ name: 'Guide' }}
>
  {children}
</GuideKitProvider>

Warning: This exposes keys in the browser. Only use for local development.

Framework Support

Framework	Support
Next.js App Router	Full (recommended)
Next.js Pages Router	Full
Vite + React	Full
Create React App	Full
Non-React (vanilla JS)	Via `@guidekit/vanilla`

Next Steps

Provider Setup — Configuration options in depth
Hooks API — Using hooks in your components
Architecture — How GuideKit works under the hood