Quick start

This gets a bot onto a page in a few minutes: start the server, make an admin account, connect a key, create a bot from a template, and paste one line into your site.

1. Start the server

From a copy of the repo:

cp .env.example .env        # optional: set PUBLIC_URL and anything else here
docker compose -f docker/compose.yml up -d
docker compose -f docker/compose.yml logs wireface-chat

The server listens on port 8800 and keeps its data in a Docker volume mounted at /data. On first run it prints a setup token in the log:

First run: open http://localhost:8800/admin/setup and enter this setup token: ...

(Set SETUP_TOKEN in .env to choose it yourself.) Running without Docker is covered in Docker.

2. Run the setup

Open http://localhost:8800/admin/setup (or your PUBLIC_URL). The setup has four steps:

1. Account. Enter the setup token, your name, email, a password (at least 10 characters) and a name for your workspace. You become its owner.
2. Provider. Paste an API key for Anthropic, OpenAI, Google Gemini or ElevenLabs. The server checks it before saving it, then loads the models and voices it can use. Keys are encrypted at rest and never sent back to a browser. Replies need Anthropic, OpenAI or Gemini; ElevenLabs adds voices. (Keys in ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or ELEVENLABS_API_KEY are connected for you.)
3. Bot. Pick a template: Customer support, Sales concierge, Website guide (with voice on) or Blank. The new bot uses what you connected: the recommended model and a voice.
4. Install. Enter your website's address (the bot only works there), publish the bot, and copy the script tag.

3. Paste the snippet

Put the script tag on your pages, just before </body>:

<script src="https://chat.example.com/widget.js" data-bot="pk_your_bot_id" async></script>

https://chat.example.com is your server and pk_your_bot_id is the bot's public id; the admin panel fills in both. Reload your page: the launcher appears in the bottom-right corner. Click it and say hello.

Trying it locally

To test from a page on your own machine, add http://localhost:* to the bot's allowed origins (the bot's Security tab), and publish again. The microphone and camera work on localhost without HTTPS; on any other address they need HTTPS.

What next

• Give the agent its job: the bot's Identity tab holds its name, personality and instructions. Publish to make changes live.
• Choose a layout and launcher, and customise the colours and words.
• Turn on voice, add a knowledge base or tools.
• Sign your users in with identity verification.
• Put the server behind HTTPS and set PUBLIC_URL before you go live.