Cloud Persistence for AI SDK (Standalone)#

Lightweight cloud persistence for AI SDK apps without assistant-ui components.

Want the full assistant-ui experience? See with-cloud instead, which uses useChatRuntime with <Thread /> and other primitives.

Setup#

Get your project URL from cloud.assistant-ui.com

Add to .env:

NEXT_PUBLIC_ASSISTANT_BASE_URL=https://your-project.assistant-api.com
OPENAI_API_KEY=sk-...

Usage#

Zero-config (anonymous users)#

import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

function Chat() {
  // Auto-initializes anonymous cloud from NEXT_PUBLIC_ASSISTANT_BASE_URL
  const { messages, sendMessage, threads } = useCloudChat();
  // ...
}

With custom cloud instance (authenticated users)#

import { AssistantCloud } from "assistant-cloud";
import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

function Chat() {
  const cloud = useMemo(() => new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
    authToken: async () => getToken(),
  }), [getToken]);

  const { messages, sendMessage, threads } = useCloudChat({ cloud });
  // ...
}

With external thread management#

When you need thread operations in a separate component (e.g., a sidebar) or custom options like includeArchived:

// In parent or context
const myThreads = useThreads({ cloud, includeArchived: true });

// In chat component - uses your thread state
const { messages, sendMessage } = useCloudChat({ threads: myThreads });

// In sidebar component - same thread state
<ThreadList threads={myThreads.threads} onSelect={myThreads.selectThread} />

How it works#

Messages persist automatically as they complete. Thread creation is handled automatically when you send the first message — the thread is created, selected, and the list is refreshed. Call threads.selectThread(id) to switch threads, threads.selectThread(null) for a new chat.