FAQ and troubleshooting

Common questions#

Is it free?

For personal and non-commercial use, yes: Wireface Desktop and wireface-core are under the PolyForm Noncommercial License 1.0.0. Using them at work, for clients, or in a product or service you sell needs a commercial licence: £1,000 once. See Licensing.

Does Wireface have its own AI?

No. It drives the agent you already use (Claude Code, OpenCode or Codex), and the face, the voice and the speech recognition sit on top. The agent does the work, with your sign-in, model, skills and MCP servers.

Does it run on a Mac or Linux?

Wireface Desktop is for Windows 10 and 11. wireface-core, the face on its own, runs in any browser with WebGL2, on any system.

Do I need an API key?

Not to start. Without one, the classic voice on your PC reads the agent's replies. A Gemini or OpenAI key gives you the realtime voice, which follows the agent's work and answers "how's it going?" at once. See Add your keys.

Does my voice leave my PC?

No. Speech recognition runs on your PC. The realtime voice service gets the text of what you said, notes about the agent's work and its replies; ElevenLabs, if you use it, gets the text it speaks. See What is sent where.

What does it cost to run?

Wireface itself costs nothing to run. The agent and the voice services are billed by their providers as usual, and the activity panel shows the cost of each request. In a room, every agent works on every question you don't address by name.

Can I run more than one face?

Yes: --face NAME gives each one its own settings, folder, voice and look. Put them in a room so they share the microphone and take turns.

Can I have just the wireframe, without a skin?

Yes: slide Wireframe ↔ Skin all the way to Wireframe (skin_amount 0). In wireface-core, useSkin(null) takes the skin off altogether.

Installing#

Windows says "Windows protected your PC"

The installer isn't code-signed yet. Check its SHA-256 hash first (how), then choose More info, then Run anyway.

"Some of Wireface's files are missing. Please install it again."

Part of the install folder has gone, perhaps removed by antivirus or a clean-up tool. Run the installer again: your settings in data\ are kept.

The speech models didn't download

The face still starts, with captions only, and says what's missing. Check your connection, then open Settings, go to the Voice tab, and under Hearing use Install speech models. From a clone, run scripts\setup.ps1: it resumes interrupted downloads.

"the face ... is already running"

Each face can only run once. If it really isn't running (after a crash, say), delete the .running file the message names, in the face's folder.

The agent#

"... is not installed (or not on PATH)"

Install the agent and sign in to it, and check it runs in a new terminal (claude, opencode or codex). If it's installed somewhere unusual, point backend.options.cli_path at its executable (how).

The face is asleep

The agent is offline or stopped, or the face lost its connection. With Start with the face off, the agent only starts with your first message, so say or type something. If it doesn't wake, look at the panel's header for what the agent is doing, and at logs\app.log in the face's folder.

Codex never asks before it acts

That's how Codex works when run this way: its permission mode decides up front. Choose Read only under When to ask if it should only look.

The agent is working in the wrong folder

Set Working folder on the Agent tab. Until you do, it's data\sandbox.

The model I want isn't in the list

Choose Other... and type its name, or use Refresh the list.

MCP servers and skills#

How do I turn an MCP server or a skill off?

Right-click the face, choose Tools, then MCP servers... or Skills..., and use its switch. It changes the agent's own configuration, as Claude Code's /mcp and /skills, or an edit to Codex's or OpenCode's config file, would. See Turning one off.

I turned something off, but the agent still uses it

Some changes wait for the agent to restart: Claude Code's skills, and everything for OpenCode. Use Restart now on the Tools tab; the conversation continues. Claude Code's servers switch at once while its session runs, and Codex's changes apply from your next message.

"... has comments, which would be lost"

That OpenCode config file has comments, so Wireface won't rewrite it. Change it by hand ("enabled": false in the server's entry, or "disabled": true with OpenCode 2), or ask the agent to.

"[mcp_servers.NAME] isn't written as a table of its own"

That Codex server is written inline (mcp_servers.NAME = { ... }), so Wireface won't edit it. Add enabled = false to it by hand.

A server says Can't start

The program it runs isn't on this PC, or isn't on the PATH: usually Node.js (for npx) or uv (for uvx). Its details say which. Install it, then refresh the Tools tab.

A server says Needs sign-in

Sign in to it the agent's way: from /mcp in Claude Code, with codex mcp login NAME, or with opencode mcp auth NAME. Then refresh the Tools tab.

"Couldn't check the servers"

The agent's own check failed. Make sure the agent is installed and signed in, and that claude mcp list, codex mcp list or opencode mcp list works in a terminal, then refresh.

I chose Install, and nothing seems to happen

Many installs are handed to the agent as a request: look in Activity, where it asks your permission before it runs the command. Claude Code loads a new server when its session restarts, and OpenCode when it restarts. See What Install does.

How do I undo a change Wireface made to my agent's config?

Turn the switch back. To put the whole file back as it was before Wireface first changed it, copy its backup from dataackups over it: see Backups.

The voice and the microphone#

The realtime voice doesn't connect

The face says why once, in plain words: usually no key, no credit, or no network. The Voice tab's Realtime voice group shows the same. Meanwhile, with Fall back to classic voice on, the voice on your PC reads the replies. Rooms always use the classic voice.

It hears itself and answers itself

Turn off Interrupt by talking, or use headphones. With it off, the microphone rests while the face speaks.

It doesn't stop when I say its name

Check Say its name to interrupt is on, and that you're using the face's name (Agent tab, This face). Speech recognition can mishear a name: add the spellings it hears under Also called, in the Agent tab's Room group.

It reacts to the TV or other people

Turn on Ignore distant voices (Voice tab, Hearing). It learns your level as you talk. There's no wake word: while Listening is on, everything said nearby goes to the agent, so turn it off when you're not talking to it.

It doesn't speak at all

Check Voice replies is ticked in the face's menu (or Spoken replies on the Voice tab), that the speech models are installed, and your speakers.

The lips don't match the voice

On the Face tab, under Motion, Advanced: move Lip-sync timing later (+) if the mouth runs ahead of the voice, or earlier if it trails. Lip-sync strength sets how wide the mouth opens.

The face#

The face has gone

Say "come back", click the tray icon, or right-click the tray icon and choose Show face. The tray icon may be under the ^ arrow in the notification area.

It's too big or too small

Scroll over it. In the floating panel, scrolling zooms the face and Ctrl + scroll resizes the panel.

"couldn't find a face in that picture"

Use a clearer photo, taken straight on, with the mouth closed, even light, and the face filling a good part of the frame.

I picked a skin but still see the wireframe

Slide Wireframe ↔ Skin towards Skin. Anywhere short of the Skin end, the face is a blend of both, with the wireframe's lines showing over the whole of it.

It covers what I'm working on

Drag it aside, scroll to shrink it, say "go away", or turn off Always on top on the Face tab.

Settings files#

My hand-edited profile.json is ignored

If it isn't valid JSON, the face reports it and uses the defaults until it's fixed, and if it saves over the file meanwhile, it keeps yours as profile.json.bad. A single setting that isn't valid is dropped, with a warning in logs\app.log. Edit the file while the face isn't running. The rules are in the configuration reference.

How do I start a face over?

Quit it and delete its folder: data\faces\NAME\, or for the original face the files in data\ (profile.json, face.json, state.json and the rest; see Where settings live).

wireface-core#

Embeds#

The embedded face mimes without sound

Browsers allow sound only after a click. The play button (talk=) counts; a say sent before anyone has clicked mimes.

My photo face shows as the wireframe

Your own photo stays in your browser, so it can't go in an embed. Use wireface-core to host a photo face yourself.

A URL parameter does nothing

A value that isn't valid is left out quietly. Check it against the parameter list; colours are six hex digits without #.

Licensing#

Which licence do I need?

If it makes or saves money, it's commercial. Trying it on your own computer, your own projects, research you share with everyone, and charities, schools, universities, public research bodies and government are free. Using it at your job (even only for your own work), for client work, to run a business, or inside a product or service needs a commercial licence.

Is it per person or per company?

Per organisation. One licence covers everyone who works for you, including contractors on your projects.

Does it expire?

No. You pay once, and every new version is included.

Can I put Wireface in an app I sell?

Yes, changed or as it is. What you can't do is sell Wireface itself, on its own or rebranded.

The full terms, and how to buy, are on licence and pricing.

Still stuck?#

Report a problem on GitHub, or contact us. The face's logs are in logs\ in its folder (app.log and shell.log); they can hold what the agent read and ran, so check them before you share them.