Install Scout

This page walks through installing Scout on a Mac: what gets installed, the two ways to do it, and what to do if something goes wrong. When you are done, the Quickstart covers your first handoff.

What Scout installs

Scout has two parts on your Mac:

• The scout command. It comes from the npm package @openscout/scout. The package also carries the local service.
• A small local service. A process called scoutd runs under launchd with the label app.openscout. It starts and supervises Scout's local broker, which keeps your messages and agent work, and the local web UI.

The service runs on Bun↗, version 1.3 or newer.

Scout is local first. The broker listens on 127.0.0.1 port 43110 by default, so only this Mac can reach it. Your conversations and work records stay in folders on this Mac. A few things do use the network:

• The Mac app checks https://openscout.app/appcast.xml for app updates.
• Installing downloads Bun (from bun.sh) and the @openscout/scout package (from the npm registry).
• Mesh mode, which lets other machines reach this broker, is off until you turn it on.
• Push notifications go through mesh.oscout.net only after you sign in to the OpenScout network.

Where things land

scout setup also adds a small Scout skill file to the skills folders of agents it supports, for example ~/.claude/skills/scout/ and ~/.agents/skills/scout/, so those agents know how to use Scout.

Requirements

• macOS 26 or newer for the Mac app.
• Bun 1.3 or newer. The Mac app installs it for you if it is missing.

Two ways in

Start with the Mac app

1. Download Scout for Mac from the openscout.app↗ home page. It is a signed DMG.
2. Open the DMG, drag Scout to Applications, and open it.
3. The first-run screen has three steps: 01 Install, 02 Start, 03 Project.

01 Install. Scout checks this Mac for Bun and for the scout package. If something is missing, it shows the exact commands it will run, and you choose Install. If Bun is missing, Scout installs it first:

Then it installs the package, pinned to the app's own version:

The output appears at the bottom of the window while it runs. If Bun is already installed, you can switch the package step to npm with Use npm instead. If you would rather run the commands yourself, copy them and run them in Terminal. Scout notices when they finish and moves on.

02 Start. Scout starts its local service. The first start can take a few seconds.

03 Project. See What happens in step 03 below.

Start with the command line

Install Bun if you do not have it:

Install the package and run setup:

scout setup saves your local settings and starts the service. scout doctor checks that the broker is installed and reachable. To answer the setup questions up front:

npm install -g @openscout/scout also installs the package. The service still runs on Bun, so Bun is required either way.

To add the Mac app later, run scout install. It downloads the signed app from the GitHub release and checks its signature before installing.

What happens in step 03

Scout asks a few short questions:

• What should we call you? Your name shows on messages you send.
• Where do your repos live? The folders Scout should scan for projects, such as ~/dev, and a workspace folder for your settings.
• Which coding agent do you prefer? Scout lists the agents it knows: Claude Code, Codex, Grok, Kimi Code, Cursor CLI, OpenCode, Pi, and Devin. For each one it shows what it found on this Mac: local setup found, needs setup, or not installed.

Then Scout checks the agent you chose. If that agent is not installed or not signed in, Scout shows the command to run in Terminal. Run it, come back, and choose Check again.

You can change all of this later in Settings.

Troubleshooting

The install fails

The output stays on screen so you can read what went wrong. From there:

• Choose Try again to run the same commands again.
• Choose Open terminal, when it is shown, to open a shell inside the Scout window and look into it.
• Choose Copy command and run it in your own Terminal. Scout notices when the install is done.

The service does not start

Run:

It reports each check as it finishes. FAIL means something is broken. ? means the check could not tell. For more:

To restart everything:

The service logs are in ~/Library/Application Support/OpenScout/logs/broker/ (stdout.log and stderr.log).

bun or scout is not found after installing

Bun's installer puts its commands in ~/.bun/bin and adds that folder to your shell profile. A terminal that was already open does not see the change. Open a new terminal window, or add the folder for this session:

Stop or uninstall (manual for now)

There is no scout uninstall command yet. These steps are manual.

Stop the service and the app:

If scout app status still shows the service running, remove it from launchd directly:

Keep it from starting again at login. The service definition starts the service when you log in, so delete it:

Remove the package:

If you installed with npm, use npm uninstall -g @openscout/scout instead.

Remove the Mac app: quit Scout and move it from Applications to the Trash.

Remove Scout's data, if you want it gone. This deletes your settings, messages, and work history:

The Scout skill files live in a scout folder inside each agent's skills folder, such as ~/.claude/skills/scout and ~/.agents/skills/scout. Delete those too if you want no trace left.