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>

Step 5: Set environment variables

Create a .env.local (Next.js) or .env file:

OPENAI_API_KEY=sk-...

The BuiltInAgent automatically resolves API keys from environment variables based on the model prefix:

• openai/* models read OPENAI_API_KEY
• anthropic/* models read ANTHROPIC_API_KEY
• google/* models read GOOGLE_API_KEY

You can also pass apiKey directly to BuiltInAgent if needed.

Step 6: Connect to the cloud platform (telemetry)

CopilotKit uses telemetry to understand adoption, improve the product, and provide better support. Connecting to the CopilotKit cloud platform gives you access to analytics and optional premium features.

1. Ask the user if they'd like to connect to the CopilotKit cloud platform (default: yes). 2. If yes, run the CopilotKit CLI authentication flow (verify the exact command with npx copilotkit --help as it may vary by version):

   npx copilotkit auth

3. Guide the user through the browser-based authentication that opens. 4. Once authentication completes, the CLI outputs a license key (format: ck_...). 5. Add the license key to the CopilotKitProvider:

   <CopilotKitProvider
     runtimeUrl="/api/copilotkit"
     licenseKey="ck_..."
   >

Alternatively, store it as an environment variable (COPILOTKIT_LICENSE_KEY in .env.local or .env) and reference it:

   <CopilotKitProvider
     runtimeUrl="/api/copilotkit"
     licenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
   >

See references/telemetry-setup.md for full details on what the license key enables and how to opt out.

Step 7: Verify the setup

1. Start the dev server 2. Open the app in a browser 3. The chat UI should render and connect to the runtime 4. Send a test message -- you should receive an AI response 5. Check the runtime's /info endpoint (GET) to confirm it reports available agents

Quick Reference

Package map

Endpoint factory functions

Runtime classes

Agent runners

Supported models (BuiltInAgent)

Format: "provider/model-name" string or a Vercel AI SDK LanguageModel instance.

OpenAI: openai/gpt-5, openai/gpt-5-mini, openai/gpt-4.1, openai/gpt-4.1-mini, openai/gpt-4.1-nano, openai/gpt-4o, openai/gpt-4o-mini, openai/o3, openai/o3-mini, openai/o4-mini

Anthropic: anthropic/claude-sonnet-4.5, anthropic/claude-sonnet-4, anthropic/claude-3.7-sonnet, anthropic/claude-opus-4.1, anthropic/claude-opus-4, anthropic/claude-3.5-haiku

Google: google/gemini-2.5-pro, google/gemini-2.5-flash, google/gemini-2.5-flash-lite

Any string is accepted (for custom/unlisted models); the provider is parsed from the prefix before /.

Framework Detection

Detect the project's framework before generating any setup code. The detection order matters -- check more specific signals first.

Detection Decision Tree

1. Does `angular.json` exist?
   YES -> Angular
   NO  -> continue

2. Does `next.config.{js,ts,mjs}` exist?
   YES -> Next.js (go to step 3)
   NO  -> continue to step 4

3. Does an `app/` directory exist at the project root or under `src/`?
   YES -> Next.js App Router
   NO  -> Does a `pages/` directory exist at the project root or under `src/`?
          YES -> Next.js Pages Router
          NO  -> Next.js App Router (assume App Router for new projects)

4. Does `vite.config.{js,ts}` exist AND does `package.json` list `react` as a dependency?
   YES -> Vite + React
   NO  -> Unknown / standalone backend only

What Differs Per Framework

Next.js App Router

• Runtime location: src/app/api/copilotkit/[[...slug]]/route.ts (multi-route) or src/app/api/copilotkit/route.ts (single-route)
• Provider placement: In a "use client" page or layout component
• Route handler style: Named exports GET and POST using handle(app) from hono/vercel
• Stylesheet import: In layout.tsx: import "@copilotkit/react/styles.css"
• Env file: .env.local
• Extra deps: hono (for Hono adapter)

Next.js Pages Router

• Runtime location: Typically runs as a separate Express server (not in API routes). The Pages Router examples in the CopilotKit repo use an external Express runtime.
• Provider placement: In pages/_app.tsx or a page component. Must be a client component (default in Pages Router).
• Frontend connects to external URL: runtimeUrl points to the Express server (e.g., http://localhost:4000/api/copilotkit)
• Stylesheet import: In pages/_app.tsx or styles/globals.css: import "@copilotkit/react/styles.css"
• Env file: .env.local
• Key prop: useSingleEndpoint must be set on the provider when using single-route Express endpoints

Angular

• Runtime location: Separate backend server (Express or Hono standalone)
• Provider placement: Uses Angular-specific components from @copilotkit/angular (separate package)
• Not React-based: Does NOT use CopilotKitProvider or React hooks
• Stylesheet import: Via Angular styles configuration in angular.json
• Package: @copilotkit/angular instead of @copilotkit/react

Vite + React

• Runtime location: Separate backend server (Express or Hono standalone). Vite dev server only serves the frontend.
• Provider placement: In the root App.tsx component
• Frontend connects to external URL: runtimeUrl points to the backend server
• Stylesheet import: In main.tsx or App.tsx: import "@copilotkit/react/styles.css"
• Env file: .env (Vite exposes vars prefixed with VITE_)
• Note: API keys should NOT be prefixed with VITE_ -- they belong on the backend server, not exposed to the browser

Standalone Backend (Express)

• No framework detection needed -- this is a backend-only setup
• Uses: @copilotkit/runtime and @copilotkit/agent
• Does NOT need: @copilotkit/react or @copilotkit/core
• Endpoint factories: createCopilotEndpointExpress (multi-route) or createCopilotEndpointSingleRouteExpress (single-route), both from @copilotkit/runtime/express
• Env file: .env (loaded via dotenv)

Standalone Backend (Hono)

• Same as Express but uses createCopilotEndpoint or createCopilotEndpointSingleRoute from @copilotkit/runtime
• Served via: @hono/node-server with serve({ fetch: app.fetch, port })

File-Level Detection Commands

When implementing framework detection in a skill, check these files:

# Next.js
ls next.config.{js,ts,mjs} 2>/dev/null

# App Router vs Pages Router
ls -d app src/app 2>/dev/null       # App Router
ls -d pages src/pages 2>/dev/null   # Pages Router

# Angular
ls angular.json 2>/dev/null

# Vite + React
ls vite.config.{js,ts} 2>/dev/null
grep -q '"react"' package.json 2>/dev/null

# Package manager
ls pnpm-lock.yaml 2>/dev/null && echo "pnpm"
ls yarn.lock 2>/dev/null && echo "yarn"
ls package-lock.json 2>/dev/null && echo "npm"
ls bun.lockb 2>/dev/null && echo "bun"

Runtime Architecture

The CopilotKit v2 runtime (@copilotkit/runtime) is the server-side component that manages agent execution, thread state, and communication with the frontend via the AG-UI protocol (SSE-based events).

Core Concepts

CopilotRuntime

CopilotRuntime is the main entry point. It is a compatibility shim that delegates to either CopilotSseRuntime (default) or CopilotIntelligenceRuntime depending on configuration.

import { CopilotRuntime } from "@copilotkit/runtime";

// SSE mode (default) -- in-memory thread state
const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  runner: new InMemoryAgentRunner(),  // optional, this is the default
});

// Intelligence mode -- durable threads via CopilotKit Intelligence Platform
const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  intelligence: new CopilotKitIntelligence({ ... }),
  identifyUser: (request) => ({ id: "user-123" }),
});

Constructor options (`CopilotRuntimeOptions`):

Agents

Agents implement the AbstractAgent interface from @ag-ui/client. CopilotKit provides BuiltInAgent (from @copilotkit/agent) as a ready-to-use implementation backed by the Vercel AI SDK.

import { BuiltInAgent, defineTool } from "@copilotkit/agent";
import { z } from "zod";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",         // "provider/model" string or LanguageModel instance
  prompt: "You are helpful.",       // System prompt
  temperature: 0.7,                // Sampling temperature
  maxSteps: 5,                     // Max tool-calling iterations (default: 1)
  tools: [                         // Server-side tools
    defineTool({
      name: "getWeather",
      description: "Get current weather for a city",
      parameters: z.object({
        city: z.string(),
      }),
      execute: async ({ city }) => {
        return { temp: 72, condition: "sunny" };
      },
    }),
  ],
});

BasicAgent is an alias for BuiltInAgent (same class, exported for convenience).

BuiltInAgent configuration:

AgentRunner

The AgentRunner abstract class controls how agent execution is managed. It has four methods:

abstract class AgentRunner {
  abstract run(request: AgentRunnerRunRequest): Observable<BaseEvent>;
  abstract connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
  abstract isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
  abstract stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
}

Built-in runners:

• `InMemoryAgentRunner` -- Default. Stores thread state (events, runs) in process memory using a global Map keyed by thread ID. Survives hot reloads via Symbol.for on globalThis. Suitable for development and single-instance deployments.
• `IntelligenceAgentRunner` -- Used automatically when CopilotIntelligenceRuntime is configured. Connects to the Intelligence Platform via WebSocket for durable, distributed thread management.

Endpoint Factories

Endpoint factories create HTTP handlers that expose the runtime's functionality. There are four variants across two HTTP frameworks (Hono, Express) and two routing styles (multi-route, single-route).

Multi-Route Endpoints

Each operation gets its own HTTP path under the base path:

Hono (`createCopilotEndpoint`):

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
  cors: {                           // optional CORS config
    origin: "https://myapp.com",    // string, string[], or function
    credentials: true,              // enable for HTTP-only cookies
  },
});

Express (`createCopilotEndpointExpress`):

import { createCopilotEndpointExpress } from "@copilotkit/runtime/express";

const router = createCopilotEndpointExpress({
  runtime,
  basePath: "/api/copilotkit",
});
app.use(router);

Single-Route Endpoints

All operations go through a single POST endpoint. The operation is identified by a method field in the JSON body. This is simpler to deploy (one route, no catch-all needed).

Hono (`createCopilotEndpointSingleRoute`):

import { CopilotRuntime, createCopilotEndpointSingleRoute } from "@copilotkit/runtime";

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

Express (`createCopilotEndpointSingleRouteExpress`):

import { createCopilotEndpointSingleRouteExpress } from "@copilotkit/runtime/express";

const router = createCopilotEndpointSingleRouteExpress({
  runtime,
  basePath: "/",  // relative to where it's mounted
});
app.use("/api/copilotkit", router);

When to Use Which

Middleware

The runtime supports before/after request middleware for cross-cutting concerns (auth, logging, rate limiting).

const runtime = new CopilotRuntime({
  agents: { default: agent },
  beforeRequestMiddleware: async ({ request, path }) => {
    // Validate auth, return modified request or void
    const token = request.headers.get("Authorization");
    if (!token) {
      throw new Response(JSON.stringify({ error: "Unauthorized" }), {
        status: 401,
      });
    }
    return request;  // or return void to pass through unchanged
  },
  afterRequestMiddleware: async ({ response, path, messages, threadId }) => {
    // Log, audit, etc. Non-blocking (errors are caught and logged).
    console.log(`Completed request to ${path}, thread: ${threadId}`);
  },
});

afterRequestMiddleware receives reconstructed messages from the SSE stream and the threadId/runId extracted from the RUN_STARTED event.

CORS

All endpoint factories enable CORS by default with origin: "*". For production with credentials (cookies), configure explicit origins:

Hono endpoints:

createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
  cors: {
    origin: "https://myapp.com",
    credentials: true,
  },
});

Express endpoints: CORS is handled internally via the cors middleware with permissive defaults. Customize by wrapping the router or adding your own CORS middleware upstream.

Frontend side: Set credentials: "include" on CopilotKitProvider to send cookies:

<CopilotKitProvider runtimeUrl="/api/copilotkit" credentials="include">

CopilotCloud Telemetry Setup

What is CopilotCloud?

CopilotCloud is CopilotKit's hosted platform that provides:

• Usage analytics -- see how users interact with your AI features (message volume, tool usage, session duration)
• Error monitoring -- surface runtime errors and failed agent interactions
• Premium features -- access to hosted runtimes, advanced agent orchestration, and priority support (requires a paid plan)

The license key is a lightweight identifier that connects your local CopilotKit instance to CopilotCloud. It does not gate any open-source functionality -- CopilotKit works fully without it.

The npx copilotkit auth flow

Running the CLI command starts an interactive authentication (verify the exact command with npx copilotkit --help as it may vary by version):

npx copilotkit auth

1. The CLI opens your default browser to the CopilotCloud login/signup page. 2. Sign in with GitHub, Google, or email. 3. Select or create a project in the CopilotCloud dashboard. 4. The CLI receives the license key and prints it to stdout:

   Successfully authenticated!
   Your license key: ck_abc123...

If the browser does not open automatically, the CLI prints a URL you can copy-paste manually.

Where to put the license key

Option A: Inline in CopilotKitProvider

Pass the key directly as a prop:

<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  licenseKey="ck_abc123..."
>
  {children}
</CopilotKitProvider>

This is the simplest approach for quick prototyping but exposes the key in source code.

Option B: Environment variable (recommended)

Add the key to your environment file:

Next.js (.env.local):

NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY=ck_abc123...

Vite (.env):

VITE_COPILOTKIT_LICENSE_KEY=ck_abc123...

Then reference it in the provider:

// Next.js
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  licenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
>

// Vite
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  licenseKey={import.meta.env.VITE_COPILOTKIT_LICENSE_KEY}
>

The NEXT_PUBLIC_ or VITE_ prefix is required because the license key is used on the client side. It is safe to expose -- the key is a project identifier, not a secret.

Opting out

To disconnect from CopilotCloud, simply remove the licenseKey prop from CopilotKitProvider (and delete the environment variable if you set one). No other changes are needed -- CopilotKit will continue to function normally without it.

Sources

Files and directories read from CopilotKit/CopilotKit to generate this skill's references. Generated: 2026-03-28

framework-detection.md

• examples/v2/ (Angular, React, Node, Node-Express, Next Pages Router directory structures)
• examples/integrations/ (integration example directory structures for framework patterns)
• packages/v2/runtime/src/ (endpoint factories: createCopilotEndpoint, createCopilotEndpointExpress, createCopilotEndpointSingleRoute)
• packages/v2/react/src/ (CopilotKitProvider props, stylesheet imports)
• packages/v2/angular/src/ (Angular component package structure)

runtime-architecture.md

• packages/v2/runtime/src/ (CopilotRuntime, CopilotRuntimeOptions, AgentRunner, InMemoryAgentRunner, IntelligenceAgentRunner)
• packages/v2/runtime/src/endpoints/ (createCopilotEndpoint, createCopilotEndpointExpress, createCopilotEndpointSingleRoute, createCopilotEndpointSingleRouteExpress, CORS config, route definitions)
• packages/v2/runtime/src/intelligence-platform/ (CopilotKitIntelligence, CopilotSseRuntime, CopilotIntelligenceRuntime)
• packages/v2/agent/src/ (BuiltInAgent, BasicAgent, defineTool, ToolDefinition, resolveModel, MCPClientConfig)
• packages/v2/shared/src/ (TranscriptionService, BeforeRequestMiddleware, AfterRequestMiddleware)

assets/express-runtime.ts

• packages/v2/runtime/src/ (CopilotRuntime constructor, createCopilotEndpointSingleRouteExpress)
• packages/v2/agent/src/ (BuiltInAgent, defineTool, ToolDefinition)
• examples/v2/node-express/ (Express server setup patterns)

assets/nextjs-app-router-route.ts

• packages/v2/runtime/src/ (CopilotRuntime, createCopilotEndpoint, InMemoryAgentRunner)
• packages/v2/agent/src/ (BuiltInAgent)
• examples/v2/react/ (Next.js App Router route handler patterns)

assets/nextjs-app-router-page.tsx

• packages/v2/react/src/ (CopilotKitProvider, CopilotChat component exports)
• examples/v2/react/ (Next.js App Router page component patterns)