# Install Legion (instructions for an AI agent)

You are an AI agent. A person asked you to install Legion on their computer. This file is the whole procedure. Follow it in order, do not improvise, and stop and report if a step fails.

Legion is a local, Claude-only multi-agent desktop app (Node service on 127.0.0.1 plus an Electron window), version 0.2.0, MIT licensed. Source: https://github.com/dnh33/legion. Today it installs from source (the README lists signed installers and prebuilt releases as not available yet).

## Rules

1. Tell the person what you are about to run before you run it, and wait for a yes before step 4 (the install itself). Reading and checking are fine without asking.
2. Run as the person's normal user. Do not use admin or sudo. Do not disable SmartScreen, antivirus or any other protection. If Windows shows a SmartScreen prompt for a `.cmd` file, tell the person; the installer is unsigned and that prompt is expected.
3. Do not read, copy, print or send the person's credentials: not `~/.claude`, not `config.json`, not any API key or token. Legion's own code never reads, copies or stores their Claude credentials, and nothing here needs you to handle them.
4. Do not paste secrets into this chat or into logs. If a step needs the person to sign in or enter a key, tell them to do it themselves.
5. Do only what this file lists. If something else seems needed, stop and ask.
6. Never run `npm run mcp-config` yourself: it prints the MCP token, which is a password, and your transcript would keep it. Never type or pipe the word `DELETE` anywhere (the uninstaller asks for it to purge data; only the person may answer). Never enter credentials at a git prompt: set `GIT_TERMINAL_PROMPT=0` for git commands, and if a clone needs a login, stop.
7. Setup runs `npm ci` (downloads packages and the Electron binary) and builds on this machine. Only run it on the source you just cloned from the URL above.

## Step 1. Check the requirements (no changes yet)

Run and report the output:

```
node --version     # needs v20.10 or newer
git --version
claude --version   # Claude Code; the person must be signed in
```

- Node older than 20.10, or missing: stop and tell the person to install a current Node.js LTS, then continue.
- git missing: stop and tell the person to install git.
- Claude Code: `claude --version` only shows that the CLI is installed, not that the person is signed in. Ask the person to confirm they are signed in. If not, they run `claude` in a terminal and use `/login` themselves. A Claude subscription or an API key is required. Legion uses whichever account Claude Code is signed in to. Doctor (step 5) checks the sign-in again.
- Windows 10 or 11 is the supported path. macOS and Linux work from a dev install (below).

## Step 2. Get the source

Work in a folder outside any existing Legion install, and set `GIT_TERMINAL_PROMPT=0` so git never waits for a password.

Windows (PowerShell):

```
mkdir $HOME\src -Force; cd $HOME\src
$env:GIT_TERMINAL_PROMPT = '0'
git clone https://github.com/dnh33/legion.git
cd legion
```

macOS and Linux:

```
mkdir -p ~/src && cd ~/src
GIT_TERMINAL_PROMPT=0 git clone https://github.com/dnh33/legion.git
cd legion
```

If the clone fails with an authentication or not-found error, stop: the repository may not be public yet. Tell the person.

## Step 3. Look before installing (Windows)

```
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -DryRun
```

`-DryRun` shows what setup would do without changing anything. Summarise it for the person. If it lists a running Legion, say so plainly: step 4 force-stops every Legion process it finds, including ones from another folder and any task in flight or approval card waiting, so get an explicit yes for that too. Setup installs for the current user only, into `%LOCALAPPDATA%\Programs\Legion`, copies the source there, installs dependencies, builds the app and adds Desktop and Start-menu shortcuts. It refuses to install over a folder that is not empty and not already a Legion install. Add `-InstallDir "C:\Some\Folder"` only if the person asks for another location.

## Step 4. Install (after the person says yes)

Windows:

```
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -Yes
```

`-Yes` asks no questions: it stops a running Legion (matched by Legion's own folder and package name, by process ID), installs and launches. `-ExecutionPolicy Bypass` applies to this one process only, and is what `setup.cmd` itself uses; if a Group Policy still blocks PowerShell scripts, stop and tell the person. The command on the website, `.\setup.cmd`, runs the same script; from an agent's shell (input redirected) it takes the defaults without asking, including stopping a running Legion, so prefer the explicit command above.

macOS and Linux (dev install, run inside the cloned folder):

```
npm ci
npm start      # builds, then opens the desktop app; runs until closed
```

`npm start` does not exit while Legion runs, so start it in the background (or ask the person to run it in their own terminal) and carry on with step 5.

On a machine with no display (a server, a container), build and run the headless core instead, which is enough for the MCP integration:

```
npm ci && npm run build
npm run core   # runs until stopped; start it in the background
```

## Step 5. Check that it works

- Windows: confirm the install folder exists and contains `start-legion.cmd`: `%LOCALAPPDATA%\Programs\Legion`. The Desktop and Start-menu shortcuts are named Legion.
- With the core running, `GET http://127.0.0.1:4747/health` needs no token and answers with a small JSON object. (4747 is the default port; the desktop app keeps the port it chose at launch. If the core was only just started, poll for up to about 30 seconds before calling it failed.)
- Ask the person to look at the Legion window and open **Doctor** in the title bar (or type `/doctor`). Doctor checks Node, config, Claude sign-in, the optional boat.dev key and the workspace folder, and says how to fix each failure. Report what the person tells you it shows.

On first launch Legion creates `config.json` in its data folder (`%USERPROFILE%\.legion` on Windows, `~/.legion` elsewhere) with a fresh auth token. Leave that file alone.

## If something fails

- Sign-in problem in Doctor: the person runs `claude` in a terminal and uses `/login`.
- Port already in use: another process holds 4747. Tell the person; do not kill unknown processes.
- Setup says the target folder is not empty: do not delete it. Tell the person and ask.
- Antivirus or SmartScreen blocks a `.cmd` file: tell the person; do not work around it.
- Anything else: stop, show the exact error, and ask. Do not retry in a loop.

## Optional, only if the person asks

- **Agent VMs (boat.dev).** Optional; without a key agents work locally. The person creates an API key in the boat.dev dashboard and puts it in `config.json` as `"boat": { "apiKey": "..." }`, or sets the `BOAT_API_KEY` environment variable. Never ask them to paste the key to you.
- **Drive Legion from Claude Code or Cowork over MCP.** Do not run `npm run mcp-config` yourself. Ask the person to run it in their own terminal: it prints ready-to-paste snippets that contain the real MCP token, which is a password (it can run agents under the `ask` ceiling, and the VM tool has no Legion approval card). Never put it in chat or logs.
- **Update later.** Run setup again from a newer source folder; it updates in place.
- **Uninstall.** Run `uninstall.cmd` in the install folder. Data in `%USERPROFILE%\.legion` is kept unless the person adds `/purge` and types the confirmation themselves. Never type or pipe it for them.

## What Legion is not

Claude only (Codex or ChatGPT are a possible later addition, not a feature). A personal tool for one machine: do not expose it to a network, host it for others or share a subscription through it. Agents it runs can execute code on the machine, so approval modes matter. Read the threat model before relying on it: https://github.com/dnh33/legion/blob/main/SECURITY.md

## Report back

Tell the person: what you ran, what each check printed, whether Doctor passed, and anything you skipped. Keep it short and exact.

Site: https://getlegion.xyz/