# Vue

> Connect a Vue app to Copilot Runtime with CopilotKit.

`@copilotkit/vue` provides Vue 3 components and composables for CopilotKit. This guide gets you to a working Vue app with a chat UI backed by a local [Copilot Runtime](/vue/ag2/backend/copilot-runtime) and `BuiltInAgent`.

The runtime runs on your server, keeps model credentials out of the browser, and exposes the `default` agent that `CopilotChat` uses automatically.

## Start with your coding agent [#start-with-your-coding-agent]

Use this prompt to connect your Vue app to Copilot Runtime with the selected agent backend, then verify a working conversation. You can also follow the manual steps below.

<PageAgentPrompt />

## Prerequisites [#prerequisites]

- An OpenAI API key (or another model provider supported by [Model Selection](/model-selection))
- Vue 3.3+
- Node.js 20+

## Getting started [#getting-started]

<Steps>
    <Step>
        ### Create your Vue app [#create-your-vue-app]

        If you don't have one already:

        ```bash
        npm create vue@latest my-copilot-app
        cd my-copilot-app
        npm install
        ```
    </Step>
    <Step>
        ### Install CopilotKit [#install-copilotkit]

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

        <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn']}>
            <Tab value="npm">
                ```bash
                npm install @copilotkit/vue @copilotkit/runtime
                npm install -D tsx typescript @types/node
                ```
            </Tab>
            <Tab value="pnpm">
                ```bash
                pnpm add @copilotkit/vue @copilotkit/runtime
                pnpm add -D tsx typescript @types/node
                ```
            </Tab>
            <Tab value="yarn">
                ```bash
                yarn add @copilotkit/vue @copilotkit/runtime
                yarn add -D tsx typescript @types/node
                ```
            </Tab>
        </Tabs>
    </Step>
    <Step>
        ### Create the Copilot Runtime [#create-the-copilot-runtime]

        Add a small runtime server that hosts Copilot Runtime at `/api/copilotkit` and registers a `default` built-in agent:

        <Callout type="warn" title="Already have an agent? Do not use BuiltInAgent">
          `BuiltInAgent` is CopilotKit's own agent. It calls the model directly.
          Registering it as `default` means chat talks to it, not to an agent you
          already wrote. It replaces your agent rather than connecting to it.

          If you already have a LangGraph, CrewAI, Mastra, ADK, Pydantic AI, or
          other agent, use your framework's quickstart for the runtime wiring so
          it registers your agent instead. You can still use the Vue frontend
          steps on this page.
        </Callout>

        ```ts title="server.ts"
        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-6-luna",
              prompt: "You are a helpful assistant for a Vue app.",
            }),
          },
        });

        const port = Number(process.env.PORT ?? 8200);

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

        <Callout type="info" title="Vite and Copilot Runtime run on separate origins">
          Vite serves the Vue app (usually on `http://localhost:5173`) while the runtime server runs on `http://localhost:8200`. Because the browser calls across those origins, `cors: true` is required for local development. `createCopilotNodeListener` does not enable CORS by default.
        </Callout>
    </Step>
    <Step>
        ### Import the styles [#import-the-styles]

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

        ```ts title="src/main.ts"
        import { createApp } from "vue";
        import App from "./App.vue";
        import "@copilotkit/vue/styles.css"; // [!code highlight]

        createApp(App).mount("#app");
        ```
    </Step>
    <Step>
        ### Connect to Copilot Runtime [#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.

        ```vue title="src/App.vue"
        <script setup lang="ts">
        import { CopilotKitProvider, CopilotChat } from "@copilotkit/vue/v2"; // [!code highlight]
        </script>

        <template>
          <!-- [!code highlight:8] -->
          <CopilotKitProvider
            runtime-url="http://localhost:8200/api/copilotkit"
          >
            <div style="height: 100vh">
              <CopilotChat />
            </div>
          </CopilotKitProvider>
        </template>
        ```

        <Callout type="info" title="Pick your chat layout">
          `CopilotChat` is the full-height chat surface. Use `CopilotSidebar` for a fixed side panel with open/close behavior, or `CopilotPopup` for a floating panel with a toggle button. They share core agent and chat wiring, but each surface also has layout-specific props and behavior.
        </Callout>
    </Step>
    <Step>
        ### Run the runtime and app [#run-the-runtime-and-app]

        Start Copilot Runtime in one terminal:

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

        Start the Vue app in another terminal:

        ```bash
        npm run dev
        ```

        Open the dev server URL (Vite prints it, usually `http://localhost:5173`), send a message, and you'll see it stream back through Copilot Runtime.

        <Accordions className="mb-4">
            <Accordion title="Troubleshooting">
                - **Chat renders unstyled**: Make sure you imported `@copilotkit/vue/styles.css` in your app entry.
                - **No response from the agent**: Confirm the runtime server is running and `http://localhost:8200/api/copilotkit/info` returns agent information.
                - **CORS errors**: The Vite app and the runtime server use different origins. Keep `cors: true` in `createCopilotNodeListener` for local development. It is CORS-disabled by default. Configure an explicit allowed origin before deploying.
                - **Model auth errors**: Confirm `OPENAI_API_KEY` is set in the terminal running `npx tsx server.ts`.
            </Accordion>
        </Accordions>
    </Step>
    <Step>
        ### Open Inspector and confirm setup [#open-inspector-and-confirm-setup]

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

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

        More detail: [Inspector](/vue/ag2/inspector).
    </Step>
</Steps>

## Where to go next [#where-to-go-next]

- [Copilot Runtime](/vue/ag2/backend/copilot-runtime): the backend layer this frontend connects to.
- [Generative UI](/vue/generative-ui/tool-based): render a tool result as a card or another interactive surface instead of plain text.
- [AG-UI Streams](/vue/AG-UI-Streams): persist conversations and work with the thread API directly.
- [Threads Drawer](/vue/prebuilt-components/copilot-threads-drawer): add a ready-made thread switcher beside the chat.
- [Vue API reference](/reference/vue): find the current `@copilotkit/vue/v2` component and composable APIs.

The Vue reference also covers slot-based customization, thread management, interrupts, and lazy-loaded custom elements for SSR.
