cana.build
Twins: an agent inside your product
A Twin is an agent you design on cana.build, with its own model, instructions, look and tools, and put on your website with one script tag or call from your product through the developer API.
How it works
The idea in 5 steps
- 1
You design the agent once
A Twin has its own name, model, instructions, welcome message and suggested prompts. It starts as a draft that only you can open.
- 2
It can use real tools
Give it built-in skills, your connected apps or your own MCP server, so it can look up an order or open a ticket instead of only chatting.
- 3
It wears your brand
Theme, accent and background colours, an avatar, the corner it sits in and its fallback message make it look like part of your product.
- 4
Limits keep usage in check
Message caps per visitor and for the whole Twin, plus a message for visitors once a limit is reached, stop a busy day turning into a surprise.
- 5
Publish it where people are
One widget on the sites you allow, a hosted page at its own address, or the developer API. Publish to go live; pause it and it stops answering for everyone.
Tutorial
Step by step
Before you start
- A cana.build account
- Optional: the apps it should use connected in Settings, Integrations
- For the widget: access to your website's code and server
- 1
Start a new Twin
Open Twins in the sidebar and click Create Twin.
You'll see: The New App form opens on its first step, Identity.
- 2
Name it and say what it does
Fill in Name and Describe what it does, keep Start with a blank app selected, then click Continue.
You'll see: The Behavior step, with the model and prompt fields.
Tip: Choose Convert an existing Chat instead to start from a conversation you already had.
- 3
Set its behaviour
Pick a Model, write the System prompt, and add a Welcome message and a few Suggested prompts. Click Continue.
You'll see: The Tools step, with built-in skills such as File upload you can switch on.
- 4
Create the draft
Choose the skills it needs and click Create draft.
You'll see: The Twin's own page, with a draft badge and tabs such as Skills, Personality & look and Install.
- 5
Make it look like your product
Open Personality & look. Set the Theme, Accent color, Avatar, Bubble position and Fallback message, then click Save.
You'll see: The save bar changes from Unsaved changes to Saved.
Tip: Untick Cana branding to hide the Powered by Cana line.
- 6
Set limits
Open Limits & billing. In Per identified user and Per app (total), set Max messages and Per window, write the Over-limit message, and Save.
You'll see: Each limit card saved, and This month showing how much of your AI allowance the Twin has used.
- 7
Install it on your site
Open Install, add your site under Allowed origins and click Add, then follow the three numbered steps there: create your secret key, add one route to your server, add the widget to your page.
You'll see: Your site listed under Allowed origins and the chat bubble on your page.
- 8
Try it, then publish
Click Preview to open the hosted page and ask it a question. When the answers are right, click Publish.
You'll see: The badge changes from draft to live, and a Pause button takes the place of Publish.
Worked example
A returns helper for an online shop
Your support inbox fills with the same returns questions. A Twin on the help page can answer them in your colours, any hour, and only on your own site.
You type
You help customers of Acme Outdoor with returns. Returns are free within 30 days with the receipt. Ask for the order number, explain the steps, and if the item is damaged, ask them to email support@acme.example.
- 1.Create Twin, name it Returns helper, paste the prompt into System prompt
- 2.Suggested prompts: How do I return an item? and My item arrived damaged
- 3.Personality & look: your brand Accent color, Bubble position Bottom right
- 4.Install: add your shop under Allowed origins, add the widget, then Publish
Result: The bubble sits on every help page, answers returns questions in your words and colours, and stops at your message cap instead of running up usage.
Troubleshooting
If something doesn't work
- Visitors can't open the Twin
- Check the badge next to its name. A draft Twin opens only for you, and a paused one answers nobody. Click Publish or Resume.
- The widget doesn't appear on my site
- Your site's address must be listed under Allowed origins in Install, with the same scheme and domain, for example https://shop.example.com.
- Clicking Publish shows Publish anyway?
- Cana's readiness check found a setup gap. Read the warning: you can still publish, but one way of reaching the Twin (widget or API) won't work until you fix it.
- Visitors see the over-limit message
- A limit in Limits & billing was reached. Raise Max messages or lengthen Per window, or wait for the window or allowance to reset.
For you
Launch a customer agent your team can tune, with limits in place
A Twin gives your team one place to manage the agent's instructions, tools, look and limits. A/B tests and analytics show what works, and rate limits and a spend cap keep usage predictable.
Support deflection
Answer common questions on the help page and hand the rest to people with context.
Test before rollout
Run an A/B test on two welcome messages and keep the one with more completed forms.
Predictable usage
Set messages per hour and a monthly spend cap so a busy day doesn't surprise you.
What changes for managers: A customer-facing agent that improves over time, within limits you set.
Technical details
What it connects to, and the controls you have
- Ways to use it
- A website widget, a hosted page at cana.build/a/<slug>, or the developer API
- Developer API
- A chat-completions-compatible endpoint, threads and runs with streamed events, and client tools your own code runs when a run pauses for action
- Keys and tokens
- Server-side secret keys (cak_live_…), plus short-lived visitor tokens minted by your server
- Controls
- Allowed origins for the widget; message caps per identified user and per Twin over a minute, hour or day; a monthly spend cap can be set from Cana Desktop or the API
- Lifecycle
- Draft (only you), Live (public), Paused (unreachable) and Archived; archived Twins can be restored as drafts
- Improve it
- Forms the Twin asks visitors to fill, A/B tests on prompt, model and welcome, and analytics
Why Cana
What you get here
- One script tag puts a Twin on your site; the same Twin is reachable through a developer API
- Client tools let your own code answer the Twin's tool calls, so your data stays behind your API
- Allowed sites, rate limits and a monthly spend cap are set per Twin
- Draft, Live, Paused and Archived states control who can reach it
