Troubleshooting & FAQ

Find what you see below and work through the steps in order. Most fixes are a chat command typed in the channel, or ufo doctor run on the machine your agents use.

#An agent does not answer

1. Look for a banner above the message box. Agent machine is offline means the machine isn't connected — see The machine shows offline.
2. Check that agents may answer here. If the channel is set to Human only (or someone typed !human), agents only answer when you @mention them. Type !human to turn agent replies back on.
3. See if it's busy. Type !queue. Processing means it's still working; your message waits its turn.
4. Stop a stuck reply. Type !stop (or press Stop on the thinking bar), then send your message again.
5. Restart the machine's sessions. Type !restart. This stops running work in every channel on the machine; conversations are kept and carry on with the next message.
6. Restart UFO Server itself. Type !relaunch. Every UFO Server process on the machine stops and starts fresh, and it's back in a few seconds.

#An agent answers but seems confused

• Type !compact when a long conversation gets slow or forgetful. It shrinks the conversation so the agent has room again.
• Type !new to start a fresh conversation in the channel. Messages stay visible; memories and skills are kept.
• To undo a turn that went wrong, use Rewind to here in the message menu (⋮) — see How do I…?.

#The machine shows offline

The banner says Agent machine is offline — messages will send, but agents won't reply until it reconnects. Settings → Machine shows Offline and the last time it was heard from (Last heartbeat …).

1. Make sure the computer is on, awake and online.

2. Make sure UFO Server is running on it — open the UFO Server app, or in a terminal run ufo service status.

3. Run the health check on that machine:

   ufo doctor
   

   It checks setup, pairing, the connection, the engines and whether UFO is running, and says what to do for anything that fails.

4. Do what it says. The common ones:

On UFO Cloud, Cloud machine is sleeping is normal: send a message and it wakes in a few seconds.

#A model sign-in expired

You see sign-in expired or a Reconnect button in the channel, or the agent fails on every message.

1. Type !connect. It lists each plan — Claude, OpenAI (ChatGPT), xAI (Grok), Google (Gemini) — as connected, sign-in expired or not connected.
2. Press Reconnect (or Connect) next to the plan and finish the sign-in. Or type it directly: !connect claude, !connect openai, !connect grok, !connect google.
3. To use a different account, type !connect disconnect <plan> first, then connect again.

The sign-in belongs to the machine, so the machine must be online. For a model that runs on an API key, check the key under Settings → Credentials or Agents → Models. More in Models & credentials.

#The pairing code does not work

The machine shows an 8-character code. You type it into UFO as the Connection code and press Connect.

• Code expired or already used. A code lasts 10 minutes and works once. Start again on the machine to get a new one: press Connect this machine on the UFO Server setup page, or run ufo install in a terminal.
• The button says Replace & connect. The workspace already has a machine. Connecting swaps it, and your agents move to the new one. A workspace has one machine.
• Wrong machine paired. Pair the right one the same way — it replaces the other. To disconnect a machine yourself, run ufo unpair on it.

#My Chrome is not connected

Settings → This device should say Connected under Let agents use your Chrome.

1. Check the UFO Browser Bridge extension is installed in that Chrome (chrome://extensions).
2. Click the UFO icon in Chrome's toolbar. Let my agents use this Chrome must be on, and not paused.
3. If the popup asks you to sign in, choose Sign in with a code and approve the code at Settings → This device → Connect a Chrome.
4. Remember it only works for your requests — an agent working for someone else won't use your Chrome.

Step by step: Browser automation.

#Computer use does not work

1. Use the UFO desktop app for Mac or Windows. The web app and phones can't do this.
2. In Settings → This device, switch on Allow … to use … for this workspace. Each workspace has its own switch.
3. On a Mac, grant Accessibility and Screen & System Audio Recording, then press Check again.
4. After you pressed Stop on the bar, access is off in every workspace — switch it on again.
5. Keep the UFO desktop app running. And ask yourself: it only works for your own requests.

Step by step: Let agents use your computer.

#Voice calls are missing

• No waveform button and no Live button: live voice is off for this workspace. A workspace admin or owner turns it on in Settings → Live voice.
• No waveform button in one channel: that channel is Human only.
• The call says Microphone access was blocked: allow the microphone for UFO in your browser or system settings, then call again.

More in Talk by voice.

#A file link in chat does not open

Agents often post a full path to a file on the machine, like /home/you/reports/summary.png. If it says Couldn't read this file — the machine may be offline:

1. Check the machine is online (see above).
2. Check the file is inside the machine's home folder, or inside a folder the owner added in Settings → Machine → Shared folders. Everything else on the machine is blocked.
3. Check the path is complete and the file still exists — browse to it in Drive, on the tab with the machine's name.

More in Terminal & files.

#FAQ

#Does my computer need to stay on?

Yes. Agents run on your machine, so when it sleeps they stop answering. Keep it awake, use a small always-on computer, or use UFO Cloud.

#Which computers can run the agents?

A Mac with Apple Silicon, a Linux x86_64 computer, or 64-bit Windows. Intel Macs aren't supported. See Quickstart.

#How do I update the machine?

When a new version is out, Settings → Machine shows Update to v… on the machine's card (workspace owners and admins). Or type !update in any channel. Running replies aren't cut off.

#Do I need an API key?

No. Agents can run on a plan you already pay for — sign in with !connect. See Models & credentials.

#Where does my data live?

See Privacy & data.

#Related

• Chat commands
• Machines & the agent host
• The ufo command line
• Known limits