Copilotkit Setup

CopilotKit Setup

Prerequisites

Live Documentation (MCP)

This plugin includes an MCP server (copilotkit-docs) that provides search-docs and search-code tools for querying live CopilotKit documentation and source code.

• Claude Code: Auto-configured by the plugin's .mcp.json -- no setup needed.
• Codex: Requires manual configuration. See the copilotkit-debug skill for setup instructions.

Environment

Before starting setup, verify:

1. Node.js >= 18 (required for fetch globals used by the runtime)
2. An AI provider API key (one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY)
3. A React-based frontend (Next.js App Router, Next.js Pages Router, Vite + React, or Angular)
4. A backend capable of running the runtime (same Next.js app via API routes, or a standalone Express/Hono server)

Framework Detection

Before generating any code, detect the project's framework by checking files in the project root. See references/framework-detection.md for the full decision tree.

Quick summary:

Setup Workflow

Step 1: Install packages

All packages use the @copilotkit namespace.

Frontend (React) packages:

npm install @copilotkit/react @copilotkit/core

Runtime packages (backend):

npm install @copilotkit/runtime @copilotkit/agent

If the runtime runs in the same Next.js app as the frontend, install all four packages together.

For standalone Express backends, also install Express adapter dependencies:

npm install express cors
npm install -D @types/express @types/cors

Step 2: Configure the runtime

The runtime is the server-side component that manages agent execution. See references/runtime-architecture.md for details.

There are two endpoint styles:

1. Multi-route (Hono) -- uses createCopilotEndpoint. Requires a catch-all route ([[...slug]] in Next.js). Each operation (run, connect, stop, info, transcribe, threads) gets its own HTTP path.
2. Single-route (Hono or Express) -- uses createCopilotEndpointSingleRoute or createCopilotEndpointSingleRouteExpress. All operations go through a single POST endpoint with method multiplexing.

Next.js App Router (recommended: multi-route with Hono)

Create src/app/api/copilotkit/[[...slug]]/route.ts:

import {
  CopilotRuntime,
  createCopilotEndpoint,
  InMemoryAgentRunner,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);

This requires hono as a dependency:

npm install hono

Next.js App Router (alternative: single-route)

Create src/app/api/copilotkit/route.ts:

import {
  CopilotRuntime,
  createCopilotEndpointSingleRoute,
  InMemoryAgentRunner,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotEndpointSingleRoute({
  runtime,
  basePath: "/api/copilotkit",
});

export const POST = handle(app);

When using single-route, the frontend must set useSingleEndpoint on the provider (see Step 3).

Standalone Express Server

Create src/index.ts:

import express from "express";
import { CopilotRuntime } from "@copilotkit/runtime";
import { createCopilotEndpointSingleRouteExpress } from "@copilotkit/runtime/express";
import { BuiltInAgent, defineTool } from "@copilotkit/agent";
import { z } from "zod";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
});

const app = express();

app.use(
  "/api/copilotkit",
  createCopilotEndpointSingleRouteExpress({
    runtime,
    basePath: "/",
  }),
);

const port = Number(process.env.PORT ?? 4000);
app.listen(port, () => {
  console.log(`CopilotKit runtime listening at http://localhost:${port}/api/copilotkit`);
});

For multi-route Express, use createCopilotEndpointExpress instead (imported from @copilotkit/runtime/express).

Standalone Hono Server (non-Vercel)

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { serve } from "@hono/node-server";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({ model: "openai/gpt-4o" }),
  },
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

serve({ fetch: app.fetch, port: 8787 });

Requires @hono/node-server:

npm install hono @hono/node-server

Step 3: Set up the frontend provider

Wrap your application with CopilotKitProvider from @copilotkit/react.

Important: Import the stylesheet in your root layout:

import "@copilotkit/react/styles.css";

Next.js App Router

In src/app/page.tsx (or a client component):

"use client";

import { CopilotKitProvider, CopilotChat } from "@copilotkit/react";

export default function Home() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <div style={{ height: "100vh" }}>
        <CopilotChat />
      </div>
    </CopilotKitProvider>
  );
}

Connecting to an external runtime

When the runtime runs on a separate server (e.g., Express on port 4000):

<CopilotKitProvider
  runtimeUrl="http://localhost:4000/api/copilotkit"
  useSingleEndpoint
>
  {children}
</CopilotKitProvider>

Set useSingleEndpoint when the backend uses single-route endpoints (createCopilotEndpointSingleRoute or createCopilotEndpointSingleRouteExpress).

CopilotKitProvider key props

Step 4: Add a chat UI component

CopilotKit provides three pre-built chat layouts:

Example with sidebar:

<CopilotKitProvider runtimeUrl="/api/copilotkit" showDevConsole="auto">
  <YourApp />
  <CopilotSidebar
    defaultOpen
    width="420px"
    labels={{
      modalHeaderTitle: "AI Assistant",
      chatInputPlaceholder: "Ask me anything...",
    }}
  />
</CopilotKitProvider>