Docs
ALIENZ Open UFO

Machines & UFO Server

Keep the computer your agents run on healthy. One machine per workspace, keep it awake, start on login, update UFO Server, run ufo doctor, and fix an offline machine.

Your agents work on one computer: the machine running UFO Server. It can be a Mac (Apple Silicon), a Windows PC (x64) or a Linux machine (x86-64). Setting it up is in Quickstart. This page is about keeping it running.

Check the machine

Settings → Machine shows the paired computer: its name, Online or Offline, when it was last seen, and the UFO Server version.

Setting there What it does
Update Installs a newer UFO Server (see below)
Web terminal Lets the workspace owner open a shell on the machine. Off by default
Shared folders Extra folders, beyond the home folder, that the workspace can open. See Terminal & files
Browser proxy Sends the agents' browser through another network. See Browser automation

One machine per workspace

Each workspace has one machine, and one machine serves one workspace.

  • Replace the machine: set up UFO Server on the new computer and connect it. UFO warns "This workspace already has a machine — connecting swaps it, and your agents move over". Confirm with Replace & connect.
  • Move a machine to another workspace: on that computer run ufo install, then type the code it shows into the other workspace.
  • Disconnect a machine: on that computer run ufo unpair.

Keep agents available

If the machine is off or asleep, your agents can't work. Messages still send, and the channel says Agent machine is offline until it comes back.

  • While UFO Server runs, it keeps the computer from falling asleep on its own. The screen can still turn off.
  • If you put the computer to sleep yourself, for example by closing a laptop lid, agents pause until it wakes.
  • On Linux, the installer keeps UFO Server running after you log out, so an SSH server works.
  • For agents that stay online with your own computer off, use UFO Cloud.

Start UFO Server when you log in

Setup turns this on for you. To check or change it, run on the machine:

ufo service status      # is it set to start at login?
ufo service install     # turn it on
ufo service uninstall   # turn it off

Where UFO Server shows a tray or menu-bar icon, its Start at Login item does the same.

Update UFO Server

  1. When a new version is out, the Settings button tells you: machine update available.
  2. Open Settings → Machine and press Update to vX. Owners and admins can do this.

Running agent turns are never cut off: new messages go to the new version right away, and turns already running finish first. You can also type !update in any channel.

Find out what is wrong

On the machine, run:

ufo doctor

It checks the setup, the pairing and connection, the AI engines (Claude Code, OpenCode, Node.js), whether UFO Server is running (and not twice), and start at login. For each problem it tells you how to fix it.

Other useful commands: ufo config shows the current setup, ufo setup opens the setup and permissions page. All commands: The ufo command line.

Fix a machine that is offline or stuck

Work down this list:

  1. Is the computer on and awake? Wake it or turn it on.
  2. Is UFO Server running? Open it from Applications or the Start menu. On a server, ufo service status shows whether the service is set up.
  3. Run ufo doctor on the machine and follow what it says.
  4. Agents answer but hang, from any device, type in a channel:
Type When
!restart An agent is stuck. Stops what's running and clears waiting messages; conversations pick up on the next message
!dedupe Two copies of UFO Server are running. Stops the extra ones
!relaunch UFO Server itself is wedged. Stops it and starts it fresh a few seconds later; running tasks end

All ! commands: Chat commands.