---
title: Machines
description: Run chats on your other Macs and on your servers, from the app or the terminal.
canonical_url: https://lookout.itoowasinarcadia.com/docs/machines
type: guide
section: Use Lookout
last_updated: 2026-10-22
related:
  - https://lookout.itoowasinarcadia.com/docs/account
  - https://lookout.itoowasinarcadia.com/docs/cli
  - https://lookout.itoowasinarcadia.com/docs/cli-reference
  - https://lookout.itoowasinarcadia.com/docs/worktrees
  - https://lookout.itoowasinarcadia.com/docs/mac-app
  - https://lookout.itoowasinarcadia.com/docs/other-apps
---

> Every page of these docs: https://lookout.itoowasinarcadia.com/llms.txt

# Machines

Run chats on your other Macs and on your servers, from the app or the terminal.

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:

```sh
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](https://lookout.itoowasinarcadia.com/docs/machines#manage)); running the line again upgrades
it too.

These variables go before `sh` in the line:

| Variable | What it does |
|---|---|
| `LOOKOUT_ACCOUNT=you` | The account to join, by username or email: your devices get the request and nothing waits on the terminal |
| `LOOKOUT_NAME=vps-1` | The machine's name (default: the hostname) |
| `LOOKOUT_REPLACE=old-name` | Takes over an offline machine of that name after a reinstall |
| `LOOKOUT_USER=name` | As root, the user Lookout runs as (default `lookout`) |
| `LOOKOUT_PROJECTS_DIR=path` | Where cloned repositories go (default `~/projects`) |
| `LOOKOUT_NO_SERVICE=1` | Installs no service: run `lookout up` yourself |
| `LOOKOUT_UNINSTALL=1` | Removes the command, its releases and its service |

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](https://lookout.itoowasinarcadia.com/docs/machines#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](https://lookout.itoowasinarcadia.com/docs/agents#hosts)).

## Run chats from the terminal

From any machine signed in to your account:

```sh
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.

| Settings › Devices | `lookout machines` | What it means |
|---|---|---|
| **Online** | online | Connected and taking chats |
| **Not answering** | degraded | Connected, but its heartbeat is late, its clock is off, or it reports a problem such as no signed-in provider. Chats start there unless the heartbeat is late |
| **Asleep** | asleep | The Mac is asleep. It takes chats again when it wakes |
| **Offline**, **Offline for 3 hours** | offline | Not connected: it quit, sharing is off, or the connection dropped |
| **Signed out** | signed out | Its session ended or was revoked. Sign in on that machine again |

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:

| Item | What it does |
|---|---|
| **Rename** | Changes the name your devices show |
| **Update** | For a machine with the `lookout` command: parks its live chats, installs the latest signed release and restarts. The parked chats resume when it comes back, and commands they were running keep running through the restart. A machine that is behind shows **Needs an update** and an **Update now** button on its row |
| **Turn off automatic updates** | For a machine with the `lookout` command, which otherwise installs each new signed release by itself the same way **Update** does: once a release has been the newest for 15 minutes, so releases minutes apart cost one restart. A paused or parked machine waits. **Turn on automatic updates** brings it back |
| **Pause new chats** | New chats from apps you connect are refused there. Running chats go on. **Take new chats** lifts it |
| **Park running chats** | Running chats stop at a safe point and pick up again when Lookout next starts there. It takes no new chats until then |
| **Remove** | Takes it off your account at once. For a server still answering or seen in the last day, the confirmation offers the line that uninstalls Lookout there |

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.

```sh
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.

| Flag | What it does |
|---|---|
| `--max N` | Caps the chats from connected apps running at once on the machine |
| `--per-project N` | Caps the chats from connected apps running at once in one project |
| `--per-client N` | Caps the chats one connected app runs at once |
| `--load-per-core N` | Holds while the 1-minute load average is above N per core |
| `--mem-min MB` | Holds while less memory than this is available |
| `--memory-pressure LEVEL` | Holds at this memory pressure or above: 1 normal, 2 warning, 4 urgent, 8 critical |
| `--cpu-pressure PCT` | On Linux, holds while CPU stall time is at least this percent |
| `--hold-paths PATH,...` | Holds while any of these paths on the machine is a file, or a folder with something in it, such as another system's busy marker or job queue. Running chats go on |
| `--drain on` | Holds every new turn from connected apps until you turn it off |
| `--cordon on` | Refuses new chats from connected apps. Running chats and their follow-ups go on |
| `--auto-resume off` | Stops Lookout continuing a connected app's turn that a crash cut off. On, the default, it continues the turn once, on the next start |
| `--auto-update off` | Stops a machine with the `lookout` command installing each new signed release by itself. On, the default, it updates within about an hour of a release, at a safe point |
| `--agents on` | Runs your [agents](https://lookout.itoowasinarcadia.com/docs/agents#hosts) on the machine, around the clock. Only you can set it |
| `--agents-only on` | Refuses every new chat on the machine that isn't one of its agents': yours, a connected app's, and any agent's Delegate. Only you can set it |
| `--agents-max N` | Refuses a new agent on the machine past N: one you create there, one you move or import there. Only you can set 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:

```sh
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
```

| Flag | What it does |
|---|---|
| `--memory-max SIZE` | The most memory Lookout and its chats may use together; past it the kernel stops processes inside |
| `--memory-high SIZE` | Above this, Lookout is slowed and its memory reclaimed. Set it a little under `--memory-max` |
| `--cpu-weight N` | Lookout's share of the CPU when the machine is busy, 1 to 10000 (the default is 100) |
| `--io-weight N` | Lookout's share of the disk when it is busy, 1 to 10000 (the default is 100) |

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`):

```sh
lookout git setup --name "Your Name" --email you@example.com
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](https://lookout.itoowasinarcadia.com/docs/worktrees#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.

## Related

- [Account and devices](https://lookout.itoowasinarcadia.com/docs/account.md): Your Lookout account: signing up, signing in on a Mac, adding a device, the Recovery Key and the web dashboard.
- [CLI](https://lookout.itoowasinarcadia.com/docs/cli.md): The lookout command on Linux and macOS: install it, sign in, run chats, and use it in scripts.
- [CLI reference](https://lookout.itoowasinarcadia.com/docs/cli-reference.md): Every lookout command and flag as the command's own help prints them, and what each exit code means.
- [Worktrees](https://lookout.itoowasinarcadia.com/docs/worktrees.md): Give a chat its own branch and folder, then merge its work back into your project.
- [Mac app](https://lookout.itoowasinarcadia.com/docs/mac-app.md): Install the Mac app, keep it up to date, and find its logs.
- [App access](https://lookout.itoowasinarcadia.com/docs/other-apps.md): Drive Lookout from another app over MCP, or from Claude Code with its plugin.