Running Chameleon locally requires a few steps that differ from a production setup. This article covers the known limitations, the workarounds that actually work, and how to debug installation issues specific to local development.
💡 Need help fast? Ask Copilot to help you diagnose your localhost setup. Try prompts like "Chameleon isn't loading on localhost — how do I debug this?" or "How do I set up HTTPS for local development with Chameleon?" Copilot can walk you through the steps based on your specific situation.
HTTPS is required
Chameleon only loads on secure HTTPS connections. A plain http://localhost setup will not work.
You have three main options for getting HTTPS locally:
Method | Notes |
Self-signed certificate | Sufficient for running the snippet. Most local dev setups support this. |
ngrok | Creates a public HTTPS URL tunnelled to your local port. Works in theory, but auth redirects inside the app often cause issues. |
Custom | Use a domain like |
How to debug installation issues on localhost
Use the following commands in your browser console to diagnose what is happening.
Step 1 — Check the snippet and user identification:
chmln.Snippet.debug()
A healthy output looks like:
Chameleon snippet loaded, and running in end-user mode. User profile loaded with id=XXXX, uid=YYYY
If this returns clean, the snippet installation is working. The issue is elsewhere.
Step 2 — Check which Experiences are loading and why:
chmln.debug()
Expand the tours or launchers dropdowns to see why specific Experiences are or are not showing.
Step 3 — Force a specific Experience to show:
chmln.show('YOUR_TOUR_ID')
Replace YOUR_TOUR_ID with the actual Experience ID. This bypasses audience and URL rules and shows the Experience directly — useful for confirming the snippet is working even when normal display conditions are not met.
💡 Read How to find the ID of a Chameleon Experience if you need to locate your Experience ID.
Known Limitations and Issues
The Builder does not work on localhost
This is a confirmed, known limitation. The Chameleon Builder Chrome Extension cannot open on localhost due to Chrome Extension security restrictions. Attempting to open it will result in a "something went wrong" error or the Builder will simply fail to load. This cannot be fixed from within the Extension.
The Chameleon snippet itself works fine on localhost; your end users can see Experiences. The restriction is only on the Builder.
If you need the full Builder experience during development, use one of the workarounds below.
Localhost does not appear in the Dashboard
Your localhost domain will not show up in the Domains or Environments pages in the Chameleon Dashboard, even when the snippet is running correctly. This is expected behaviour — localhost is not tracked as a managed domain.
If you see an installation prompt that is still blocking you, Chameleon support can manually ungate the installation prompts on your account.
Still stuck?
If the snippet is not loading at all, read How to verify your Chameleon installation.
If the Builder is not opening for reasons unrelated to localhost, read I don't see the Chameleon Builder.
Contact Chameleon support via the "Get Help" page in your Dashboard. Include the output of
chmln.Snippet.debug().