Installation

Install with AI

Click Copy Prompt at the top of this page and paste it into Codex, Claude Code, Cursor, or your coding assistant with your project open. Your assistant will install the public skill, connect the Agents MCP, and add the integration for your framework. You complete browser sign-in and approve the workspace and permissions.

See Building with AI for the full setup path, or follow the installation steps below.

Requirements

• Chrome or Edge 120+, Firefox 121+, or Safari 17.2+

React integrations require React and React DOM 19 or newer. The optional vanilla loader has no framework dependency.

Next.js is not required. If your application uses Next.js, the Agent's Next.js entry point requires Next.js 15 or newer.

HeroUI Agent is currently an invite-only beta. You need Agents access, an Agent ID, and a workspace key with auth_tokens:create before the embed can connect to the hosted runtime. Your coding assistant can create the Agent and an owner-authorized integration key through MCP, or you can use the dashboard. Request beta access if you do not have it yet.

Get your Agent credentials

Open the Agents dashboard, select your Agent, then open Settings in the sidebar and copy the Agent ID.

Next, open API keys in the same workspace and create a key with auth_tokens:create permission.

Install the React bridge

Install @heroui/agent. The package is the small customer-page bridge; React and React DOM are optional package peers used by its React entry points. The conversation UI and its renderer dependencies load from the hosted Agent iframe.

Skip this section if your website does not use React. The vanilla loader needs no browser package or framework dependency.

npm install @heroui/agent@latest

pnpm add @heroui/agent@latest

yarn add @heroui/agent@latest

bun add @heroui/agent@latest

Content Security Policy

Allow the hosted Agent origin in frame-src (or child-src for older policies):

Content-Security-Policy: frame-src https://agent.heroui.pro

Use https://staging-agent.heroui.pro for staging. Credentials are never placed in the iframe URL; the bridge exchanges the browser credential for a short-lived, origin-bound iframe session after a versioned handshake.

The optional vanilla loader also needs its origin in script-src:

Content-Security-Policy: frame-src https://agent.heroui.pro; script-src 'self' https://agent.heroui.pro

Optional vanilla loader

Applications without React can load the revalidated bridge directly from HeroUI. The UI and all heavy dependencies still run inside the iframe:

<script src="https://agent.heroui.pro/loader.js" defer></script>
<script>
  window.addEventListener("heroui-agent:loaded", () => {
    window.agent = window.HeroUIAgent.mount({
      agentId: "your_agent_id",
      getAuthToken: ({anonymousId, agentId}) =>
        fetch("/api/heroui-agent/auth-token", {
          method: "POST",
          headers: {"Content-Type": "application/json"},
          body: JSON.stringify({anonymousId, agentId}),
        }).then((response) => response.json()),
      tools: [
        {
          name: "view_product",
          description: "Open a product in this application",
          icon: "view",
          parameters: {
            type: "object",
            properties: {productId: {type: "string"}},
            required: ["productId"],
          },
          execute: ({productId}) => {
            window.location.assign(`/products/${productId}`);
            return {opened: true};
          },
        },
      ],
    });
  });
</script>

Vanilla tool parameters use raw JSON Schema. The returned controller supports show, hide, toggle, newConversation, refreshAuth, shutdown, and destroy.

Add environment variables

Keep the API key and a server-side copy of the Agent ID in your server environment. The embed also needs the Agent ID in the browser:

HEROUI_AGENT_API_KEY=he_...
HEROUI_AGENT_ID=your_agent_id

HEROUI_AGENT_API_KEY=he_...
HEROUI_AGENT_ID=your_agent_id
NEXT_PUBLIC_HEROUI_AGENT_ID=your_agent_id

HEROUI_AGENT_API_KEY=he_...
HEROUI_AGENT_ID=your_agent_id
VITE_HEROUI_AGENT_ID=your_agent_id

HEROUI_AGENT_API_KEY must stay server-only. The Agent ID is safe to expose; it identifies the Agent but does not authorize requests.

Choose an entry point

The React and Next.js entry points expose the same public bridge. The Next.js entry point is packaged for App Router applications and is the recommended import in Next.js projects. All integrations can use @heroui/agent/server on the server to exchange the API key for short-lived browser tokens; its React peer dependency is optional when only the server entry point is used.

Both entry points and the server helper use https://api.heroui.pro by default.

Next step

Continue to the Quickstart to create a token endpoint, mount the embed, and send your first message.