Installation - CopilotKit

CopilotKit supports multiple frontend frameworks and runtime environments. Choose the setup that matches your stack.

Framework Support

React

Full support with hooks and components

Angular

Angular 19+ with signals and standalone components

Vanilla JS

Framework-agnostic integration

React Installation

Prerequisites

Node.js 18 or later
React 18 or 19
Next.js 14+ (recommended) or Create React App

Install Packages

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime

Package Overview

@copilotkit/react-core - Core hooks and providers (CopilotKit, useCopilotAction, useCoAgent, etc.)
@copilotkit/react-ui - Pre-built UI components (CopilotSidebar, CopilotPopup, CopilotChat)
@copilotkit/runtime - Server-side runtime for handling agent execution

Next.js Setup (App Router)

Create the runtime endpoint

Create app/api/copilotkit/route.ts:

app/api/copilotkit/route.ts

import {
  CopilotRuntime,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/runtime";
import { NextRequest } from "next/server";

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

// Create the Next.js API handler
export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    endpoint: "/api/copilotkit",
  });
  
  return handleRequest(req);
};

Add the provider

Update app/layout.tsx:

app/layout.tsx

import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit" agent="default">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Use in your pages

Create app/page.tsx:

app/page.tsx

"use client";

import { CopilotSidebar } from "@copilotkit/react-ui";
import { useCopilotAction } from "@copilotkit/react-core";

export default function Home() {
  useCopilotAction({
    name: "sayHello",
    description: "Say hello to the user",
    parameters: [
      { name: "name", type: "string", required: true }
    ],
    handler: ({ name }) => {
      alert(`Hello ${name}!`);
    },
  });
  
  return (
    <main>
      <h1>My CopilotKit App</h1>
      <CopilotSidebar defaultOpen={true} />
    </main>
  );
}

CopilotKit components must be used in Client Components. Add "use client" at the top of files that use CopilotKit hooks or components.

Next.js Setup (Pages Router)

Create the API route

Create pages/api/copilotkit.ts:

pages/api/copilotkit.ts

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

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

export default copilotRuntimeNextJSPagesRouterEndpoint({
  runtime,
  endpoint: "/api/copilotkit",
});

Add the provider

Update pages/_app.tsx:

pages/_app.tsx

import type { AppProps } from "next/app";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" agent="default">
      <Component {...pageProps} />
    </CopilotKit>
  );
}

Create React App Setup

For Create React App or other React setups, you’ll need a separate backend server. See the Express Backend Setup section below.

Angular Installation

CopilotKit supports Angular 19+ with standalone components.

Install Packages

npm install @copilotkitnext/angular @copilotkitnext/runtime

Angular Frontend Setup

Configure the provider

Update src/app/app.config.ts:

src/app/app.config.ts

import { ApplicationConfig, importProvidersFrom } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { provideCopilotKit } from "@copilotkitnext/angular";

export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom(BrowserModule),
    provideCopilotKit({
      runtimeUrl: "http://localhost:4000/api/copilotkit",
    }),
  ],
};

Add the chat component

Update your component (e.g., src/app/app.component.ts):

src/app/app.component.ts

import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { CopilotChat } from "@copilotkitnext/angular";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [CommonModule, CopilotChat],
  template: `
    <main>
      <h1>My CopilotKit Angular App</h1>
      <copilot-chat [threadId]="'default'"></copilot-chat>
    </main>
  `,
})
export class AppComponent {}

Import styles

Add to your src/styles.css or angular.json:

src/styles.css

@import "@copilotkitnext/angular/styles.css";

Or in angular.json:

angular.json

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.css",
              "node_modules/@copilotkitnext/angular/styles.css"
            ]
          }
        }
      }
    }
  }
}

Angular Backend Setup

Angular apps need a separate backend server. See the Express Backend Setup or Hono Backend Setup sections below.

Vanilla JavaScript Installation

CopilotKit can be used in any JavaScript application without a framework.

Install Core Package

npm install @copilotkitnext/core

Basic Setup

import { CopilotKitClient } from "@copilotkitnext/core";

// Initialize the client
const copilot = new CopilotKitClient({
  runtimeUrl: "http://localhost:4000/api/copilotkit",
  agent: "default",
});

// Connect to the runtime
await copilot.connect();

// Send a message
copilot.sendMessage("Hello, CopilotKit!");

// Listen for responses
copilot.onMessage((message) => {
  console.log("Agent:", message.content);
});

Vanilla JS integration requires more manual setup. Consider using React or Angular for the best developer experience with CopilotKit.

Backend Runtime Setup

CopilotKit requires a runtime server to handle agent execution. Choose the option that fits your stack.

Express Backend Setup

Perfect for Node.js applications or when you need a separate backend server.

Install dependencies

npm install @copilotkitnext/runtime @copilotkitnext/agent express cors dotenv

Create the server

Create server.js or src/server.ts:

src/server.ts

import express from "express";
import dotenv from "dotenv";
import { CopilotRuntime } from "@copilotkitnext/runtime";
import { BuiltInAgent } from "@copilotkitnext/agent";
import { createCopilotEndpointSingleRouteExpress } from "@copilotkitnext/runtime/express";

dotenv.config();

const app = express();

// Create the runtime with your agent
const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({
      model: "openai/gpt-4o-mini",
    }),
  },
});

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

const PORT = process.env.PORT || 4000;
app.listen(PORT, () => {
  console.log(`CopilotKit runtime listening on http://localhost:${PORT}`);
});

Set environment variables

Create .env:

.env

OPENAI_API_KEY=your_api_key_here
PORT=4000

Start the server

node src/server.ts

Or add to package.json:

package.json

{
  "scripts": {
    "server": "node src/server.ts",
    "dev": "nodemon src/server.ts"
  }
}

Hono Backend Setup

Hono is a lightweight web framework that works with Vercel, Cloudflare Workers, and more.

import { Hono } from "hono";
import { CopilotRuntime, createCopilotEndpoint } from "@copilotkitnext/runtime";
import { BuiltInAgent } from "@copilotkitnext/agent";

const app = new Hono();

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

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

app.route("/api/copilotkit", copilotEndpoint);

export default app;

Environment Configuration

Required Environment Variables

Set these in your .env or .env.local file:

.env

# Required: Your LLM provider API key
OPENAI_API_KEY=sk-...

# Optional: Other LLM providers
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Optional: LangSmith for observability (when using LangGraph)
LANGSMITH_API_KEY=...

Model Configuration

CopilotKit uses a provider-prefixed model format:

// OpenAI models
model: "openai/gpt-4o-mini"
model: "openai/gpt-4o"
model: "openai/gpt-5.2"

// Anthropic models
model: "anthropic/claude-sonnet-4.5"
model: "anthropic/claude-opus-4"

// Google models
model: "google/gemini-2.5-pro"
model: "google/gemini-2.0-flash"

The runtime automatically uses the corresponding API key based on the provider prefix.

CORS Configuration

If your frontend and backend are on different domains, you need to configure CORS.

Express CORS

import cors from "cors";

app.use(
  cors({
    origin: "http://localhost:3000", // Your frontend URL
    credentials: true,
  })
);

Next.js CORS (if needed)

Next.js API routes handle CORS automatically when using the same domain. For cross-origin requests, add headers:

export const POST = async (req: NextRequest) => {
  const response = await handleRequest(req);
  
  response.headers.set("Access-Control-Allow-Origin", "*");
  response.headers.set("Access-Control-Allow-Methods", "POST, OPTIONS");
  
  return response;
};

Verify Installation

Test your setup with this checklist:

Check runtime connection

Open your browser’s Network tab and verify the connection to /api/copilotkit shows a successful SSE stream.

Test basic interaction

Send a message to your agent and verify you receive a response.

Test frontend actions

If you’ve defined any useCopilotAction hooks, ask the agent to trigger them.

Troubleshooting

Module not found errors

Make sure you’ve installed all required packages:

@copilotkit/react-core for React hooks
@copilotkit/react-ui for UI components
@copilotkit/runtime for the backend runtime

Runtime connection failed

Check that:

Your backend server is running
The runtimeUrl in your CopilotKit provider matches your API endpoint
CORS is configured if using separate domains
Your API key is set in environment variables

Styles not loading

Ensure you’ve imported the CSS:

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

Or for Angular:

import "@copilotkitnext/angular/styles.css";

TypeScript errors

Make sure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "types": ["node"]
  }
}

Next Steps

Now that you have CopilotKit installed, explore these guides:

Build Your First Agent

Learn how to configure and customize your agent

Add Frontend Actions

Let your agent interact with your UI

Implement Generative UI

Render dynamic UI components from your agent

Integrate with LangGraph

Use LangGraph for complex agent workflows

Need help? Join our Discord community or check the GitHub repository.

​Framework Support

React

Angular

Vanilla JS

​React Installation

​Prerequisites

​Install Packages

​Package Overview

​Next.js Setup (App Router)

​Next.js Setup (Pages Router)

​Create React App Setup

​Angular Installation

​Install Packages

​Angular Frontend Setup

​Angular Backend Setup

​Vanilla JavaScript Installation

​Install Core Package

​Basic Setup

​Backend Runtime Setup

​Express Backend Setup

​Hono Backend Setup

​Environment Configuration

​Required Environment Variables

​Model Configuration

​CORS Configuration

​Express CORS

​Next.js CORS (if needed)

​Verify Installation

​Troubleshooting

​Next Steps

Build Your First Agent

Add Frontend Actions

Implement Generative UI

Integrate with LangGraph

Framework Support

React Installation

Prerequisites

Install Packages

Package Overview

Next.js Setup (App Router)

Next.js Setup (Pages Router)

Create React App Setup

Angular Installation

Install Packages

Angular Frontend Setup

Angular Backend Setup

Vanilla JavaScript Installation

Install Core Package

Basic Setup

Backend Runtime Setup

Express Backend Setup

Hono Backend Setup

Environment Configuration

Required Environment Variables

Model Configuration

CORS Configuration

Express CORS

Next.js CORS (if needed)

Verify Installation

Troubleshooting

Next Steps