Troubleshooting & FAQ

Most problems have a 60-second fix. Work down this list first — the fastest tools are chat commands you type right in the channel.

#An agent isn't answering

#Is the host awake?

A sleeping computer means sleeping agents. Check the status dot in Settings → Machines: green means the host is online and ready.

#It's online but stuck

• !queue shows what is waiting in the channel; the channel header shows when the agent is working.
• !stop cancels a stuck task and clears the queue.
• Still quiet? !restart restarts the sessions on the host — it's safe, and it fixes most one-off hangs.

#Answering, but derailed

• !new starts a fresh session with clean context.
• !compact trims a long session's context when replies get sluggish or forgetful.

#The host seems unhealthy

Run the built-in health check on the host machine:

# on the host — prints the exact fix for anything it flags
ufo doctor

ufo doctor checks pairing, server reachability, engines, Node and service liveness, and prints the exact fix for whatever it flags. To inspect or reinstall the background service:

ufo service status    # is the service running?
ufo service install   # re-register auto-start

#A model errors out or the login expired

#Subscription logins

• ChatGPT or Grok — type !connect in the channel and a sign-in link arrives in chat. No keys.

• Claude subscription — sign in once on the host:

  # on the host, one time
  claude
  

#API-key models

Check the key in Settings → Models. Expired keys and spent quotas are the usual suspects — rotate the key or top up the account.

#Rate limits

If an agent's usage bar is running hot (≥80%), you may be rate-limited. Wait for the reset time shown on the card, or shift work to another plan or a local model.

#Pairing trouble

• Code expired or mistyped? Pairing codes are single-use — just run the installer again to get a fresh one. See Quickstart.
• Swapping machines? Pair the new one; the old machine's tokens retire automatically and its agents move over on their own.

#FAQ

#Does my computer need to stay on?

Yes — the host runs on your hardware, so if it sleeps, your agents sleep with it. Leave it awake, dedicate a small always-on box, or run the host on UFO Cloud.

#Which operating systems run the host?

macOS (Apple Silicon), Linux (x86_64) and Windows (x64). See Quickstart for the installers.

#Can I use my Claude subscription?

Yes. Sign in once with claude on the host and agents use it directly — no API key needed. See Models & credentials.

#Do I need an API key to get started?

No. If Claude Code is signed in on the host, the default agent works out of the box. The brand picker in Settings → Models is there when you want to add keys or other providers.

#Where does my data live?

Your code, files, shell and engine logins stay on your machine. Only chat syncs through UFO's edge so every device stays current. Full details in Privacy & data.

#How do I update the host?

Updates are rolling and zero-downtime — the host upgrades itself in the background and every new message is handled by the newest version. To force a check, type !update in a channel.

#I paired the wrong machine — what now?

Pair the machine you actually want; the wrong one's tokens retire automatically. Agents follow the newly paired host. No manual cleanup required.