Install Wireface

What you need#

• Windows 10 or 11, 64-bit. Wireface Desktop is built and tested on Windows 11.
• An agent, installed and signed in: Claude Code, OpenCode or Codex. The installer doesn't install them. Any skills, MCP servers and instructions you've given the agent come along, and the panel's Tools tab lists them.
• A microphone and speakers, or headphones, to talk with it out loud. You can also type.
• Optional: a Gemini or OpenAI API key for the realtime voice. Without one, a voice that runs on your PC reads the agent's replies instead.
• Optional: an ElevenLabs key for the classic voice in the cloud, and a Twilio account and number for the phone line.
• Disk and download: the installer is 133 MB, and the speech models are about 650 MB more, downloaded once the first time it starts.

No administrator rights are needed.

Download and check it#

Check the file before you run it. In PowerShell, in the folder you saved it to, this prints True:

(Get-FileHash .\WirefaceSetup-0.1.0.exe -Algorithm SHA256).Hash -eq '61eb1b5c8060a6d32c4fad7bfbf24903837ce244affb18e61f5a236bd47c1e9b'

Run the installer#

1. Run WirefaceSetup-0.1.0.exe. The installer isn't code-signed yet, so Windows may say Windows protected your PC. Once the hash matches, choose More info, then Run anyway.
2. Accept the licence. It's the PolyForm Noncommercial licence: free for personal and non-commercial use (see licence and pricing).
3. Choose whether to Create a desktop shortcut. Wireface is always added to the Start menu.
4. Leave Start Wireface ticked at the end to start it straight away.

It installs for your user only, in %LOCALAPPDATA%\Programs\Wireface. It brings its own Python, Electron and MediaPipe, so there's nothing else to install.

The first start#

The first time it starts, Wireface downloads its speech models: about 650 MB, once. A console window titled Wireface: downloading the speech models (once) shows the progress. They're what recognise your speech and give the face a voice on your PC.

If the download fails, the window stays open so you can read why, and the face starts anyway, with captions only, and tells you what's missing. To try again later, open Settings, go to the Voice tab, and under Hearing use Install speech models.

Then the face appears, floating over your windows, with a tray icon (the wireframe head) in the notification area. To get going:

1. Right-click the face and choose Settings...
2. On the Agent tab, pick your agent, and under Working folder use Choose... to pick the folder it should work in.
3. On the Voice tab, turn on Listening. (Or right-click the face and choose Type a message...)
4. Say hello.

Until you choose a folder, the agent works in data\sandbox inside the install folder. Each folder has its own conversation. More on all of this in Using the app.

Connect your agent#

Wireface runs the agent you installed, with its own sign-in. Install and sign in to it as its makers describe, then pick it in Settings on the Agent tab. Switching takes effect at once, and each agent keeps its own conversation.

Wireface looks for claude.exe, opencode.exe or codex.exe on your PATH. If you installed the agent with npm, it finds the real .exe inside the npm install. If it still can't find it, the face tells you that the agent "is not installed (or not on PATH)": point backend.options.cli_path in the face's profile.json at the executable.

See Agents and permissions for models, permissions and the rest.

Add your keys#

Claude Code, OpenCode and Codex use their own sign-in: Wireface holds no keys for them. The keys it can use are for the voice and the phone line. Set the environment variable, or paste the key into Settings.

• A key you paste is saved for that face in its secrets.json, and is used before an environment variable. It's never shown again, never written to profile.json, and never sent to the page or the activity log.
• A Windows user or system variable you set while Wireface is running is picked up within seconds: no restart needed.
• Each setting can name a different variable to read: see api_key_env in the configuration reference.

Several faces#

Each face has its own settings, folder, voice and look, so you can run several side by side. Give each one a name with --face:

& "$env:LOCALAPPDATA\Programs\Wireface\Wireface.exe" --face work
& "$env:LOCALAPPDATA\Programs\Wireface\Wireface.exe" --face home

From a clone, it's Wireface.cmd --face work. A shortcut with --face work after the target does the same. Without --face you get the original face. Starting a face that's already running is refused.

Faces running on their own don't share the microphone, so two of them would talk over each other and both answer you. Put them in a room to make them take turns. All the command line options are in the configuration reference.

Run it from source#

You need Python 3.11 or newer, Node.js and git, as well as the agent.

git clone https://github.com/compsmart/wireface-desktop wireface
cd wireface
Wireface.cmd

The first run installs everything into the folder (scripts\setup.ps1):

• a Python virtual environment in .venv;
• Electron and MediaPipe in deps\shell;
• the speech models (about 650 MB, once), in deps\models unless MODELS_DIR says otherwise.

Run scripts\setup.ps1 again at any time: it only fetches what's missing, resumes interrupted downloads, and checks that the speech models load and that a microphone and speakers are there. Add -WithKokoro to install the optional Kokoro voice as well.

For a console with the logs, or to use the face in a browser instead of the desktop window:

.venv\Scripts\python -m wireface             # logs to the console too
.venv\Scripts\python -m wireface --browser   # prints a URL to open in a browser

The tests run with .venv\Scripts\python -m pytest tests. To build the installer yourself, run scripts\build-installer.ps1: it needs Inno Setup 6. The version is in wireface\version.py.

Update#

Quit Wireface (right-click the face, Quit), then download the newer installer and run it. The latest one is always on Get started and under GitHub Releases. It installs over the old version and keeps your settings, conversations, logs and speech models. To see which version you have, look in Windows Settings, then Apps, where it's listed as Wireface with its version number (Wireface 0.1.0, for example).

From a clone, run git pull, then scripts\setup.ps1 to pick up anything new.

Uninstall#

Open Windows Settings, then Apps, find Wireface and choose Uninstall. This removes the app and the speech models.

It keeps the data folder (%LOCALAPPDATA%\Programs\Wireface\data): each face's settings, conversations, logs and saved keys. Delete that folder too to remove everything, including any API keys you pasted into Settings.

Your agent and its own settings aren't touched. Wireface may have created an AGENTS.md in folders where OpenCode or Codex worked (see AGENTS.md); delete those if you don't want them.

Install wireface-core#

wireface-core is plain ES modules with no dependencies and no build step. It runs in any browser with WebGL2 and ES modules: Chrome, Edge, Firefox, and Safari 15 and later. Node.js 18 or newer is only needed for its dev server and tests.

Try it first#

git clone https://github.com/compsmart/wireface-core.git
cd wireface-core
npm start          # a zero-dependency static server: http://127.0.0.1:5173/

Open http://127.0.0.1:5173/demo/ for the playground, with every setting on one page, or /examples/ for one small page per feature.

Add it to your project#

Install it from GitHub with npm:

npm install github:compsmart/wireface-core

import { createFace } from '@wireface/core';

Or copy the folder in, or add it as a git submodule, and import the source directly:

git submodule add https://github.com/compsmart/wireface-core.git vendor/wireface-core

import { createFace } from './vendor/wireface-core/src/index.js';

Pages must be served over http(s): browsers don't load ES modules from file://. Using Vite or another bundler? Tell the face where its assets are: see Bundlers. Then carry on with the developer guide.

The tools that make lip-sync clips need Python 3.10 or newer with numpy (pip install -r tools/requirements.txt), and ffmpeg for audio that isn't WAV.