Machines

Every Lookout on your account is a machine: the Mac app on each of your Macs, and the lookout command on a server or another computer. From any of them you can start, steer and stop chats on the others. A chat runs on its machine, with that machine's files and tools and the providers your account shares.

Add a server

The installer runs on Linux and macOS, on x64 and arm64, and needs curl, tar and git.

1. In the Mac app, open Settings › Devices and click Add a device.
2. Under A server or another computer, type a Name (optional) and copy the line under Run this on it. The line names your account, so the server's request goes to your devices.
3. Run the line on the server, as root or as the user Lookout should run as. It installs the latest signed release, prints a 6-digit code and a lookout://add/ link, and starts the service.
4. On your Mac, a banner says the server wants to join your account. Click Review, type the code, and click the Add button, which carries the server's name (such as Add vps-1). Opening the link on your Mac instead brings up the request with the code already checked.

The server then shows up under Your devices. Without the line from Add a device, run the plain line in a terminal on the server. It asks for your Lookout username or email (or Enter for a link to open on your Mac), then waits until one of your devices adds it:

curl -fsSL https://lookout.itoowasinarcadia.com/install.sh | sh

lookout login on the server asks the same at any time, and lookout login --account you skips the question.

Run as root on Linux, the installer creates the user lookout and installs everything as that user. Its service runs lookout up at boot: a systemd user unit on Linux, and a launchd agent on a Mac without the app. Once installed, it updates itself to each new signed release (Manage a machine); running the line again upgrades it too.

These variables go before sh in the line:

On a box it shares with other work, give the service less of the machine with flags after sh -s -- at the end of the line, such as sh -s -- --nice 5 --cpu-weight 50 --memory-high 75% --memory-max 90%. The flags are --nice, --cpu-weight, --io-weight, --memory-high and --memory-max; on macOS only --nice applies. A later run changes only the ones it is given. Once it is installed, lookout service sets the same limits from any of your devices (Service limits).

Open a window on another machine

1. Open Settings › Devices.
2. Under Your devices, click Open beside the machine. Open shows while the machine can take chats.

The same switch is in the Window menu under Machine, and in the search palette (⌘K): type machine and pick Machine: the machine's name. The machine the window is on carries a checkmark in both places.

The window reloads on that machine. Its projects and chats are listed, and new chats run there. The sidebar shows On and the machine's name with Back, and a chat names that machine under the message box. A chat on this Mac names no machine there. Settings, providers and accounts in that window are still this Mac's. Click Back to return.

Switching or creating a branch, and reverting or undoing changes, don't work in such a window: they say Not available in a window on vps-1 yet. If the machine stops answering, the window says so, with Back to this Mac and Choose another machine.

Agents don't follow the window: the sidebar lists your agents on every machine that runs them, and each agent's chat opens on its own machine, with that machine's name on the Machine row of its message box's + menu (Run agents on a server).

Run chats from the terminal

From any machine signed in to your account:

lookout machines
lookout exec --on vps-1 -C /home/lookout/projects/app "fix the failing test"
lookout sessions --on vps-1
lookout check THREAD --on vps-1
lookout steer THREAD "also update the changelog" --on vps-1
lookout stop THREAD --on vps-1

--on takes a machine's name or ID, or local for this machine; LOOKOUT_MACHINE=vps-1 sets it for every command. On another machine, -C takes a path that exists there, absolute or starting with ~/. Without -C, every run there shares one scratch project. exec follows the chat until it ends and skips any question the agent asks; --detach prints the chat's ID and leaves it running. A command exits with code 5 when the machine is offline, asleep, signed out or not answering.

Check a machine's status

Settings › Devices shows each device with a dot and one line; lookout machines lists the same with its own words.

When this Mac can't be reached, Settings › Devices says why under Use this Mac from your other devices, and when it tries again.

Use this Mac from your other devices

Use this Mac from your other devices, under This Mac in Settings › Devices, is on unless you turn it off. While it is on, your other devices, the lookout command and agents you connect can start, steer and stop chats on this Mac. Off, the Mac shows as offline to them. On a server, lookout share on and lookout share off do the same.

Keep awake sets whether Lookout keeps the Mac from sleeping meanwhile: When plugged in (the default), Always or Never. A Mac that sleeps shows as asleep until it wakes.

Manage a machine

Each device in Settings › Devices has a menu button at the end of its row:

A paused machine's row reads Paused, takes no new chats, with a grey dot instead of a green one, and a machine that runs its commands at low priority says Commands at low priority on its row.

For this Mac, Pause new chats and Park running chats are under This Mac. In a terminal, lookout rename vps-1 build-1, lookout remove vps-1, lookout park --on vps-1, lookout upgrade --on vps-1 and lookout capacity --on vps-1 --auto-update off do the same.

Limit what a machine takes

Apps you connect over MCP can start chats on any of your machines. The limits below apply only to those chats: a limit holds a new one until the machine has room. The chats you start yourself, in a window or with lookout exec, always start.

lookout capacity --on vps-1
lookout capacity --on vps-1 --max 2 --per-project 1
lookout capacity --on vps-1 --reset

The first command shows the machine's load and the value of each limit. Every limit is off until you set it, so with none set a chat from a connected app starts at once however busy the machine is. A held chat waits in line, showing the limit that holds it, and starts once there is room. Stop on a chat waiting in line takes it out: it doesn't start when room frees, and its message is read with the next one you send it. The caps count every turn such a chat runs: the turn its finished commands or subagents start, and the one that goes on after its plan's reset, which waits ahead of new chats. A turn that only waits on its own command, a pause or its subagents for more than 20 seconds stops counting while it waits, so the next chat in line starts; once its wait ends it takes its place back ahead of new chats, and goes on. A chat with a quota policy that is waiting in line while all its models are at their plan's limit stays there, saying until when, instead of starting only to stop at once; chats on other models start past it.

0 turns a limit off, default puts back its default, and --reset puts back every default.

To keep a server to one agent and nothing else, run lookout capacity --on vps --agents-only on --agents-max 1.

On a server shared with CI, --hold-paths gives CI the right of way: with lookout capacity --on build-1 --max 2 --hold-paths /srv/ci/active,/srv/ci/queue, no new chat from a connected app starts there while CI's marker file exists or its queue folder has an entry, and the held chat says which path holds it.

Service limits

On Linux, lookout service puts the Lookout service and everything it starts, each chat's commands included, in a systemd slice of its own with the memory, CPU and disk limits you give it:

lookout service --on build-1
lookout service --on build-1 --memory-max 4G --memory-high 3800M --cpu-weight 20 --io-weight 20
lookout service --on build-1 --reset

A size is bytes with K, M, G or T, a percentage of the machine's memory, or infinity. The first limit you set moves the service into its slice: its running chats stop at a safe point, it restarts, and they pick up again. Later changes apply at once. The command prints the limits as systemd and the kernel hold them, and lookout doctor warns when one does not hold. Connected apps set the same limits with lookout_configure_machine.

Beside these machine-wide limits, Stop all and hold on one project (its menu in the sidebar) holds that project's work until Resume project: a chat a connected app sends into it is refused outright with the code project_paused and a pointer to Resume, so an orchestrator stops sending, and agent chats in the project stay idle. Your own messages always run.

Set up git and tools on a server

Chats on a server commit and push with that machine's own git identity and credentials. Run these on the server as the user Lookout runs as (on a root install, after sudo -iu lookout):

lookout git setup --name "Your Name" --email [email protected]
printf %s "$TOKEN" | lookout git setup --host github.com --token-stdin

The token comes on stdin, never as an argument. --user sets the user name for it (default x-access-token).

Install the tools your projects build with as that user, the usual way, then restart the service (systemctl --user -M lookout@ restart lookout as root). Lookout takes the login shell's PATH when it starts. lookout doctor --on vps-1 then checks the machine's providers, git identity and credentials, the commands its projects require (see The worktree file) and free disk. Each problem it finds comes with its fix.

Remove a server

1. In Settings › Devices, open the server's menu, choose Remove, and click Remove in the dialog.
2. To take Lookout off the server too, run the line the dialog shows on it. It is the install line with LOOKOUT_UNINSTALL=1 before sh.

The uninstall keeps your Lookout data in ~/.lookout on the server. Run on its own, it signs the server out, and the server stays on your list as signed out until you remove it.