Go live checklist

This is the complete list. Do the Required steps in order. If you skip one, the chat won't load or the agent can't do anything. The Recommended steps make it better, but the chat works without them.

Required

1. Create a workspace

Sign in to the dashboard with GitHub and choose New workspace.

• Under More options, you can enter Your app's website now (for example app.acme.com) or add it later in step 4. A new workspace already allows localhost on any port for development.
• Decide now who can chat. Who can chat? can only be set here; to change it later you'd create a new workspace. Choose Signed-in users if users sign in to your app. That's the usual case, and the only one where the agent can act on someone's account.

Choose Create workspace.

Your workspace ID is the last part of the workspace's address, /app/workspaces/<workspace-id>. It's also already filled in to the setup prompt on the Install tab, so you rarely need to copy it yourself. The publishable key is under Overview → Keys & settings.

2. Add Frankie to your app

An AI agent writes the install for you. Pick one of the two ways. Each adds the chat, a sign-in token route (POST /api/frankie/token) wired to your app's existing sign-in, and the variables your app reads.

Way	Works with	What you do
Connect GitHub	Any React app and its backend: Next.js, Vite or a React SPA with Express, Fastify, Hono or Nest, Remix or React Router, and backends in other languages	Install → Connect GitHub, then pick the repository. In a monorepo, the dashboard asks which app. Frankie's install agent reads the repository and opens one draft pull request. Read its Needs you section, update your lockfile (how), and merge. See Install by pull request.
Your AI coding assistant	Any React app and its backend	Install → Use your AI coding assistant → Copy setup prompt, then paste the prompt into Claude Code, Cursor, Copilot or Windsurf at the repository root. Review the diff, push the branch and open a pull request. See Install with your AI coding assistant.

Install with your AI coding assistant

Already working in Claude Code, Cursor, Copilot or Windsurf? You don't need to connect anything. Copy the setup prompt from the Install tab (your workspace ID and key are filled in, never the secret), paste it at the repository root, and review the diff. Get the prompt.

If the frontend isn't React (Vue, Svelte, Angular, server-rendered HTML), the install agent changes nothing and tells you the SDK is React-only.

A separate API service, a monorepo, or an app shell around /chat? Check Setup requirements by architecture first. It lists what your API, sign-in and deploy must provide, and what to set for each common setup.

Check sign-in before you merge. If the install couldn't find how your app signs people in, the token route answers 501 until you fill in one lookup, and the pull request's Needs you section names the file. See The install agent couldn't wire sign-in.

3. Set the deployment variables

Set them in .env.local for development (restart the dev server afterwards) and in every environment you deploy to (Preview and Production).

Variable	Where	Notes
NEXT_PUBLIC_FRANKIE_KEY	Frontend	The publishable key. It's built into the page when the app is built, so rebuild and redeploy after setting or changing it. On other frameworks, use their public prefix (VITE_FRANKIE_KEY…).
FRANKIE_JWT_SECRET	Server only, on the backend that serves /api/frankie/token	Overview → Keys & settings → Server secret → Reveal current secret. Never commit it or expose it to the browser. Not needed if visitors chat without signing in.
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY	Server	Supabase apps only. The token route uses them to check the user's Supabase session.

All of them are explained in Environment variables. On Vercel, Connect Vercel on the Install tab (shown once a repository is connected) sets them for you.

4. Add your allowed sites

Under Overview → Keys & settings → Allowed sites, list every address the chat runs on, then choose Save sites:

• your production domain, for example app.acme.com
• each preview domain you test on
• localhost:3000 (or your dev port) for development, only if Allow localhost is off

Allow localhost (development), under the list, lets any http://localhost or http://127.0.0.1 port open the chat. It's on for new workspaces and off for workspaces created before it existed. A browser only sends a localhost origin from a page on your own computer, so it opens nothing to other sites; turn it off if you don't want it.

Listed sites must match exactly: no wildcards, www.acme.com and acme.com are different, and so are localhost and 127.0.0.1. If the list is empty, the chat loads nowhere except on localhost while Allow localhost is on.

5. Connect your API and allow at least one action

Until you do this, the agent can only answer questions: it can't do anything in your app.

1. Connect the API. A Connect GitHub install connects the OpenAPI draft it commits. After your AI assistant installs, Frankie doesn't see your API yet. Do one of these:
   • In Product agent → Connect your API, add your OpenAPI spec (for example public/frankie.openapi.json) by its URL, or choose Paste JSON instead and paste the file's contents.
   • Connect the repository on Install so Frankie reads the committed spec.
   • Paste or upload it once, and paste the new version when your API changes.
2. Allow actions. In Product agent → What may it do in your app?, switch on the actions the agent may take, then choose Save allowed actions. Everything starts off. See Actions.

6. Check that it works

Merge, deploy, then check:

1. Health. On Next.js, open https://<your-app>/api/frankie/health (the Next.js install includes it). You want "publishableKey": true, "jwtSecret": true (unless visitors chat without signing in), and "auth" set to something other than "unconfigured".
2. Token route, signed out. It should answer 401:

   curl -i -X POST https://<your-app>/api/frankie/token

   501 means sign-in isn't wired, 503 means FRANKIE_JWT_SECRET is missing, and 500 means your session lookup threw. See Troubleshooting.
3. Chat. Sign in to your app, open the chat launcher and send a message. The Install tab then shows Live on your site.

The Product agent only appears to signed-in users. If you're signed out and see nothing, it's working as designed.

4. An action, signed in. Ask the agent to do something it's allowed to. If it fails with 401, or with 404 from your app instead of your API, see Troubleshooting and Setup requirements by architecture.

Recommended

• Keep your API current. Connected through GitHub, Frankie offers updates when your routes change (Keeping your API current). Otherwise, connect your spec by URL so Frankie re-reads it at least every 30 seconds, or paste the new version in Product agent when your API changes.
• Teach it your workflows with skills.
• Match your brand under Widget. See Widget and theme.
• Add the Support and Docs agents. Set their keys and your app already shows them (how). See Agents.
• Watch for escalations. Conversations that need a person show up under Escalations.

Stuck? See Troubleshooting.