React SPA

Create your React app#

If you don't have one already:

npm create vite@latest my-copilot-app -- --template react-ts
cd my-copilot-app
npm install

An existing Create React App project works the same way — only the dev server command in the last step differs.

Install CopilotKit#

Install the React frontend package and @copilotkit/runtime for your local Copilot Runtime server:

npm install @copilotkit/react-core @copilotkit/runtime
npm install -D tsx typescript @types/node

pnpm add @copilotkit/react-core @copilotkit/runtime
pnpm add -D tsx typescript @types/node

yarn add @copilotkit/react-core @copilotkit/runtime
yarn add -D tsx typescript @types/node

Create the Copilot Runtime#

Your SPA has no server, so the runtime needs one of its own. Add a small Node server that hosts Copilot Runtime at /api/copilotkit on its own port and registers a default built-in agent:

import { createServer } from "node:http";
import { BuiltInAgent, CopilotRuntime } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({
      model: "openai:gpt-5-mini",
      prompt: "You are a helpful assistant for a React app.",
    }),
  },
});

const port = 8200;

createServer(
  createCopilotNodeListener({
    runtime,
    basePath: "/api/copilotkit",
    cors: true, 
  }),
).listen(port, () => {
  console.log(
    `Copilot Runtime listening at http://localhost:${port}/api/copilotkit`,
  );
});

Import the styles#

Import the package stylesheet once in your app entry. It's self-contained, so the chat renders without any other CSS.

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "@copilotkit/react-core/v2/styles.css"; 

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Connect to Copilot Runtime#

Point CopilotKitProvider at the runtime endpoint and drop in CopilotChat. Because the runtime registers an agent named default, the chat picks it up automatically.

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

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

Run the runtime and app#

You are running two dev servers, so they need two different ports. Start Copilot Runtime in one terminal:

export OPENAI_API_KEY=sk-...
npx tsx server.ts

Start the React app in another terminal:

npm run dev

Vite serves on http://localhost:5173 and the runtime on 8200, so the defaults don't collide. If you need to move the app, pass --port — Vite ignores the PORT environment variable, unlike Create React App:

npm run dev -- --port 3000

Open the dev server URL, send a message, and you'll see it stream back through Copilot Runtime.

Open Inspector and confirm setup#

On localhost, click the Inspector button in the corner of the app.

1. Open Agents, then Agent. Your agent is listed.
2. Send a chat message. Open Agents, then AG-UI Events. Events are moving.
3. Open Threads. The list is unlocked (Intelligence is on), or locked with Enable Intelligence (Intelligence is off).

More detail: Inspector.