Skip to content
Bunkhouse Docs

Installation

Every installation uses the same loader tag. What differs is how a session learns who the user is. Copy the complete, generated example for your site from the dashboard: open the site and choose a mode in its Install section.

Session modes

Section titled “Session modes”
  • Signed: identity token (recommended) for applications with signed-in users. Add a same-origin endpoint that returns a short-lived identity token, plus a page hook that fetches it.
  • Signed: server mint for applications that want the session created server-side. Add a same-origin endpoint that creates the session with a mint key.
  • Anonymous for public pages, only when explicitly enabled. Add only the loader; usage is limited by the site’s anonymous spending limits.
Section titled “Identity token (recommended)”

Your backend signs a short-lived identity token for the user it has already authenticated, using a signing secret (ss_...) from the site’s Keys page. The embed exchanges that token for a short agent session.

The page tells the embed how to get a token by defining window.AgentEmbedConfig.getIdentityToken before the loader:

<script>
  window.AgentEmbedConfig = {
    getIdentityToken: async () => {
      // Call your own same-origin endpoint; it authenticates with your existing session.
      const res = await fetch("/api/agent-identity", { credentials: "same-origin", cache: "no-store" });
      if (!res.ok) throw new Error("Not signed in");
      return (await res.json()).identityToken;
    },
  };
</script>
<script src="https://embed.bunkhouse.ai/embed.js" data-public-key="pk_YOUR_SITE_PUBLIC_KEY"></script>

The endpoint itself must authenticate the request with your existing session, reject signed-out users, and sign the token on the server. The dashboard’s Install section shows a complete server example for your site. Never send the signing secret to the browser.

Server mint

Section titled “Server mint”

Instead of a page hook, add data-session-endpoint to the loader. The embed posts to that same-origin endpoint; your server authenticates the user and creates the session with a mint key (sk_...):

<script src="https://embed.bunkhouse.ai/embed.js" data-public-key="pk_YOUR_SITE_PUBLIC_KEY"
  data-session-endpoint="/api/agent-session"></script>

Anonymous

Section titled “Anonymous”

Anyone who can load your allowed origins can start an anonymous session, so it is not proof of identity. Anonymous access is off until you enable it for the site, with monthly token and spend limits; usage is charged to your prepaid balance.

Reset on account changes

Section titled “Reset on account changes”

In signed modes, call window.AgentEmbed.resetSession() whenever your application signs a user in, signs them out or switches accounts, so the assistant never keeps acting for the previous user:

function onAuthChanged() {
  window.AgentEmbed?.resetSession();
}

User IDs

Section titled “User IDs”

Signed sessions carry your application’s user ID. Send a stable, opaque ID such as your database ID, not a name or email address. It is retained so you can see usage per user in the dashboard; model providers receive only a pseudonym derived from it.

Content Security Policy

Section titled “Content Security Policy”

If your page sends a Content Security Policy, add these sources to your existing directives. Merge them into your current policy; do not replace it:

script-src https://embed.bunkhouse.ai; frame-src https://embed.bunkhouse.ai; connect-src https://api.bunkhouse.ai

Agent code runs in a sandboxed iframe on the embed origin, so your page needs no 'wasm-unsafe-eval', worker-src or style nonce.

Next steps

Section titled “Next steps”