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

> Every page of these docs: https://lookout.arcadia.is/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.arcadia.is/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.arcadia.is/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; when that machine's device held your providers' key, it asks your Lookout password |
| `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.arcadia.is/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.arcadia.is/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, it went down to restart, sharing is off, or the connection dropped. A server whose service restarts it says so, and a call to it says to try again in about 30 seconds |
| **Signed out** | signed out | Its session ended or was revoked. Sign in on that machine again |

A device that is up with under 10 GB free adds it to its line, such as **8.6 GB free on disk**; under 5 GB, where
clones and worktrees start to fail, the figure is an amber badge beside its buttons. Under **This Mac**, a **Disk space**
row says the same of this Mac, signed in to your account or not. A window showing another machine with under 5 GB free
turns the sidebar's mark for it amber and says the free space under its name; with no other machine shown, this Mac
under 5 GB free gets the same amber mark with its free space, and a click opens **Settings › Devices**. **Free space** beside the badge, and on the **Disk space** row, removes
the worktrees archived chats keep on that machine once you confirm what it found
([Free the space archived chats' worktrees hold](https://lookout.arcadia.is/docs/worktrees#reclaim)).

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. Chats' commands
run at low priority by default, below Lookout itself when the machine is busy and at full speed when it is idle; a
machine where that is turned off says **Commands at normal 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 and your [agents](https://lookout.arcadia.is/docs/agents#chats) can start chats on any of your machines. The limits
below apply to those chats' turns: the one an app or an agent's Delegate starts, each message or retry it sends there,
and each turn such a chat goes on with by itself (its finished commands or subagents, its plan's reset). A limit holds
such a turn until the machine has room; it never stops a turn that is running. Where the table says connected apps, it
means agents too. The chats you start yourself, in a window or with `lookout exec`, always start, and so does every
message you send.

An agent counts as one client for `--per-client`, whichever of its chats started the work, and cordon refuses its new
chats as it does an app's. Its own chat and its routines' chats are never capped. While a drain, a hold path, or a
pressure, load or memory hold holds the machine, no chat wakes for another agent's message, a routine's fire or a
finished command; your own messages still start. An agent can also change how many chats of a
project run at once ([Start chats from an agent](https://lookout.arcadia.is/docs/agents#chats)).

```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.arcadia.is/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. A
restart of the service parks running chats and leaves their commands running: the next start takes them over.
`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.arcadia.is/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.arcadia.is/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.arcadia.is/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.arcadia.is/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.arcadia.is/docs/worktrees.md): Give a chat its own branch and folder, merge its work back into your project, and reclaim old worktrees' disk with Free space.
- [Mac app](https://lookout.arcadia.is/docs/mac-app.md): Install the Mac app, keep it up to date, and find its logs.
- [App access](https://lookout.arcadia.is/docs/other-apps.md): Drive Lookout from another app over MCP, or from Claude Code with its plugin.
