# Installation
URL: /docs/installation

Get assistant-ui running in 5 minutes with npm and your first chat component.

Quick Start \[#quick-start]

The fastest way to get started with assistant-ui.

<img alt="animated gif showing the steps to create a new project" src={__img0} />

<Steps>
  <Step>
    Initialize assistant-ui \[#initialize-assistant-ui]

    **Create a new project:**

    ```sh
    npx assistant-ui@latest create
    ```

    Or choose a template:

    ```sh
    # Minimal starter
    npx assistant-ui@latest create -t minimal

    # Assistant Cloud - with persistence and thread management
    npx assistant-ui@latest create -t cloud

    # Assistant Cloud + Clerk authentication
    npx assistant-ui@latest create -t cloud-clerk

    # LangGraph starter template
    npx assistant-ui@latest create -t langgraph

    # MCP starter template
    npx assistant-ui@latest create -t mcp
    ```

    **Add to an existing project:**

    ```sh
    npx assistant-ui@latest init
    ```
  </Step>

  <Step>
    Add API key \[#add-api-key]

    Create a `.env` file with your API key:

    ```
    OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```
  </Step>

  <Step>
    Start the app \[#start-the-app]

    ```sh
    npm run dev
    ```
  </Step>
</Steps>

Manual Setup \[#manual-setup]

If you prefer not to use the CLI, you can install components manually.

<Steps>
  <Step>
    Add assistant-ui \[#add-assistant-ui]

    <InstallCommand shadcn={["thread", "thread-list"]} manualSetupInstructions />
  </Step>

  <Step>
    Setup Backend Endpoint \[#setup-backend-endpoint]

    Install provider SDK:

    <Tabs groupId="provider" items={["OpenAI", "Anthropic", "Azure", "AWS", "Gemini", "GCP", "Groq", "Fireworks", "Cohere", "Ollama", "Chrome AI"]}>
      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/openai"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/anthropic"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/azure"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/amazon-bedrock"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/google"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/google-vertex"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/openai"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/openai"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/cohere"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "ollama-ai-provider-v2"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "chrome-ai"]} />
      </Tab>
    </Tabs>

    Add an API endpoint:

    <Tabs groupId="provider" items={["OpenAI", "Anthropic", "Azure", "AWS", "Gemini", "GCP", "Groq", "Fireworks", "Cohere", "Ollama", "Chrome AI"]}>
      <>
        <Tab value="OpenAI">
          ```ts title="/app/api/chat/route.ts" 
          import { openai } from "@ai-sdk/openai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: openai("gpt-4o-mini"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Anthropic">
          ```ts title="/app/api/chat/route.ts" 
          import { anthropic } from "@ai-sdk/anthropic";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: anthropic("claude-3-5-sonnet-20240620"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Azure">
          ```ts title="/app/api/chat/route.ts" 
          import { azure } from "@ai-sdk/azure";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: azure("your-deployment-name"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="AWS">
          ```ts title="/app/api/chat/route.ts" 
          import { bedrock } from "@ai-sdk/amazon-bedrock";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: bedrock("anthropic.claude-3-5-sonnet-20240620-v1:0"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Gemini">
          ```ts title="/app/api/chat/route.ts" 
          import { google } from "@ai-sdk/google";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: google("gemini-2.0-flash"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="GCP">
          ```ts title="/app/api/chat/route.ts" 
          import { vertex } from "@ai-sdk/google-vertex";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: vertex("gemini-1.5-pro"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Groq">
          ```ts title="/app/api/chat/route.ts" 
          import { createOpenAI } from "@ai-sdk/openai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          const groq = createOpenAI({
            apiKey: process.env.GROQ_API_KEY ?? "",
            baseURL: "https://api.groq.com/openai/v1",
          });

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: groq("llama3-70b-8192"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Fireworks">
          ```ts title="/app/api/chat/route.ts" 
          import { createOpenAI } from "@ai-sdk/openai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          const fireworks = createOpenAI({
            apiKey: process.env.FIREWORKS_API_KEY ?? "",
            baseURL: "https://api.fireworks.ai/inference/v1",
          });

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: fireworks("accounts/fireworks/models/firefunction-v2"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Cohere">
          ```ts title="/app/api/chat/route.ts" 
          import { cohere } from "@ai-sdk/cohere";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: cohere("command-r-plus"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Ollama">
          ```ts title="/app/api/chat/route.ts" 
          import { ollama } from "ollama-ai-provider-v2";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: ollama("llama3"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Chrome AI">
          ```ts title="/app/api/chat/route.ts" 
          import { chromeai } from "chrome-ai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: chromeai(),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>
      </>
    </Tabs>

    Define environment variables:

    <Tabs groupId="provider" items={["OpenAI", "Anthropic", "Azure", "AWS", "Gemini", "GCP", "Groq", "Fireworks", "Cohere", "Ollama", "Chrome AI"]}>
      <>
        <Tab value="OpenAI">
          ```sh title="/.env.local" 
          OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Anthropic">
          ```sh title="/.env.local" 
          ANTHROPIC_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Azure">
          ```sh title="/.env.local" 
          AZURE_RESOURCE_NAME="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          AZURE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="AWS">
          ```sh title="/.env.local" 
          AWS_ACCESS_KEY_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          AWS_REGION="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Gemini">
          ```sh title="/.env.local" 
          GOOGLE_GENERATIVE_AI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="GCP">
          ```sh title="/.env.local" 
          GOOGLE_VERTEX_PROJECT="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          GOOGLE_VERTEX_LOCATION="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          GOOGLE_APPLICATION_CREDENTIALS="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Groq">
          ```sh title="/.env.local" 
          GROQ_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Fireworks">
          ```sh title="/.env.local" 
          FIREWORKS_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Cohere">
          ```sh title="/.env.local" 
          COHERE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Ollama">
          ```sh
          <none>
          ```
        </Tab>

        <Tab value="Chrome AI">
          ```sh
          <none>
          ```
        </Tab>
      </>
    </Tabs>

    If you aren't using Next.js, you can also deploy this endpoint to Cloudflare Workers, or any other serverless platform.
  </Step>

  <Step>
    Use it in your app \[#use-it-in-your-app]

    <Tabs items={["Thread", "AssistantModal"]}>
      <>
        <Tab value="Thread">
          ```tsx title="/app/page.tsx" 
          import { AssistantRuntimeProvider } from "@assistant-ui/react";
          import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
          import { ThreadList } from "@/components/assistant-ui/thread-list";
          import { Thread } from "@/components/assistant-ui/thread";

          const MyApp = () => {
            const runtime = useChatRuntime({
              transport: new AssistantChatTransport({
                api: "/api/chat",
              }),
            });

            return (
              <AssistantRuntimeProvider runtime={runtime}>
                <div>
                  <ThreadList />
                  <Thread />
                </div>
              </AssistantRuntimeProvider>
            );
          };
          ```
        </Tab>

        <Tab value="AssistantModal">
          ```tsx title="/app/page.tsx" 
          // run `npx shadcn@latest add https://r.assistant-ui.com/assistant-modal.json`

          import { AssistantRuntimeProvider } from "@assistant-ui/react";
          import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
          import { AssistantModal } from "@/components/assistant-ui/assistant-modal";

          const MyApp = () => {
            const runtime = useChatRuntime({
              transport: new AssistantChatTransport({
                api: "/api/chat",
              }),
            });

            return (
              <AssistantRuntimeProvider runtime={runtime}>
                <AssistantModal />
              </AssistantRuntimeProvider>
            );
          };
          ```
        </Tab>
      </>
    </Tabs>
  </Step>
</Steps>

What's Next? \[#whats-next]

<Cards>
  <Card title="Pick a Runtime" description="Choose the right runtime for your needs" href="/docs/runtimes/pick-a-runtime" />

  <Card title="Generative UI" description="Create rich UI components for tool executions" href="/docs/guides/tool-ui" />

  <Card title="Add Persistence" description="Save and restore chat conversations" href="/docs/cloud/overview" />

  <Card title="Examples" description="Explore full implementations and demos" href="https://github.com/assistant-ui/assistant-ui/tree/main/examples" />
</Cards>