> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.method.security/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.method.security/_mcp/server.

# Run an Overwatch session

> Download, install, and start recording terminal sessions with Overwatch

Overwatch is a CLI tool that records your terminal sessions and streams them to the Method Platform, enabling session review and Report generation.

---

#### macOS / Linux

### Download the binary

Open the Overwatch session page from either entry path above. Click the information icon and download the binary under **"Download Overwatch Binary"**.

| OS    | Architecture             | Choose       |
| ----- | ------------------------ | ------------ |
| macOS | Apple Silicon (M1/M2/M3) | macOS ARM64  |
| macOS | Intel                    | macOS 64-bit |
| Linux | x86_64                   | Linux 64-bit |
| Linux | ARM64                    | Linux ARM64  |

### Make the binary executable

```bash
chmod +x ~/Downloads/overwatch

# macOS only: clear the quarantine flag if prompted
xattr -d com.apple.quarantine ~/Downloads/overwatch
```

### Run the setup wizard

```bash
~/Downloads/overwatch setup
```

The wizard will ask for:

* **Method Platform URL**: the hostname of your deployment (e.g. `yourorg.method.delivery`)
* **Menu color mode**: dark or light

After completing the wizard, on-screen instructions will appear. Follow along with the next section below.

> **Note**
>
> You can view the setup instructions again at any time by running `overwatch
>   setup --instructions`.

### Move the binary and add shell hooks

Move the binary to a permanent location on your PATH:

```bash
mv ~/Downloads/overwatch ~/.local/bin/overwatch
```

If `~/.local/bin` is not on your `$PATH`, add it to your shell config:

```bash
# Add to ~/.zshrc (zsh) or ~/.bashrc (bash)
export PATH="$HOME/.local/bin:$PATH"
```

Then add the Overwatch shell hook for your shell:

**zsh:**

```bash
echo 'eval "$(overwatch init-hooks zsh)"' >> ~/.zshrc
source ~/.zshrc
```

**bash:**

```bash
echo 'eval "$(overwatch init-hooks bash)"' >> ~/.bashrc
source ~/.bashrc
```

Open a new terminal window to pick up all changes, then verify:

```bash
overwatch --version
```

### Start a recording

In your new terminal window, run:

```bash
overwatch record
```

Overwatch will prompt you to authenticate with your platform. Follow the on-screen instructions. After authenticating, you will see a list of sessions. Select the session you created in the first step.

To end a recording, use one of the following:

* Type `exit`
* Press `Ctrl+D`
* Use the magic menu (`Ctrl+Shift+6, Ctrl+Shift+6`)

### Common options

```bash
# Record locally only, no network, saves to overwatch.out
overwatch record --run-local

# Record without any network access, save for later upload
overwatch record --airgapped
```

#### Windows

### Download the binary

Open the Overwatch session page from either entry path above. Click the information icon and download the binary under **"Download Overwatch Binary"**.

| OS      | Architecture | Choose         |
| ------- | ------------ | -------------- |
| Windows | x86_64       | Windows 64-bit |
| Windows | ARM64        | Windows ARM64  |

> **Note**
>
> Your browser may flag `overwatch.exe` as an uncommon download and remove the
> file automatically. If this happens, open the downloads panel, select **Keep**
> (or **Keep anyway**), and confirm you trust the file. See
> [Troubleshooting](#troubleshooting) for details.

### Run the setup wizard

```powershell
cd ~\Downloads
.\overwatch.exe setup
```

The wizard will ask for:

* **Method Platform URL**: the hostname of your deployment (e.g. `yourorg.method.delivery`)
* **Menu color mode**: dark or light

After completing the wizard, on-screen instructions will appear. Follow along with the next section below.

> **Note**
>
> You can view the setup instructions again at any time by running `overwatch
>   setup --instructions`.

### Move the binary and add shell hooks

Move the binary to a permanent location and add it to your PATH:

```powershell
mkdir "$env:USERPROFILE\overwatch"
mv ~\Downloads\overwatch.exe "$env:USERPROFILE\overwatch\overwatch.exe"
setx PATH "$($env:PATH);$env:USERPROFILE\overwatch"
```

Allow PowerShell to run local scripts (only needed once):

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Then add the Overwatch shell hook to your PowerShell profile:

```powershell
if (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }

Add-Content -Path $PROFILE -Value "`nif (Get-Command overwatch -ErrorAction SilentlyContinue) { overwatch init-hooks powershell | Out-String | Invoke-Expression }"
```

Open a new terminal window to pick up all changes, then verify:

```powershell
overwatch --version
```

### Start a recording

In your new terminal window, run:

```powershell
overwatch record
```

Overwatch will prompt you to authenticate with your platform. Follow the on-screen instructions. After authenticating, you will see a list of sessions. Select the session you created in the first step.

To end a recording, use one of the following:

* Type `exit`
* Press `Ctrl+D`
* Use the magic menu (`Ctrl+Shift+6, Ctrl+Shift+6`)

### Common options

```powershell
# Record locally only, no network, saves to overwatch.out
overwatch record --run-local

# Record without any network access, save for later upload
overwatch record --airgapped
```

---

## During a recording

While a session is active, a status bar is visible at the bottom of your terminal showing the session name, command count, and a reminder of available controls.

### Opening the menu

Press `Ctrl+Shift+6` twice to open the Overwatch Menu. From here you can:

| Option               | Description                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------- |
| **Pause Recording**  | Stops capturing commands. The status bar turns yellow to indicate the session is paused. |
| **Resume Recording** | Resumes capturing after a pause.                                                         |
| **Stop Recording**   | Immediately exits Overwatch and kills the terminal session.                              |
| **Magic Inputs**     | Opens a submenu to re-inject shell hooks into the current shell.                         |

### Magic Inputs

If you drop into a subshell during a session (e.g. `ssh` into another machine, `sudo su`, `docker exec`), the Overwatch hooks may not be active in the new shell. Open the menu with `Ctrl+Shift+6, Ctrl+Shift+6` and select **Magic Inputs** to inject the appropriate hooks.

> **Note**
>
> These injections run in the shell you are currently in (the subshell), not the
> original parent shell.

* **Inject zsh prompt**: for zsh subshells
* **Inject bash prompt**: for bash subshells
* **Inject /bin/sh prompt**: for environments that only have sh (e.g. minimal Docker containers)
* **Inject powershell prompt**: for PowerShell subshells

If you exit back to the parent shell, that shell's hooks remain whatever they were before.

---

## Troubleshooting

**`overwatch: command not found`**
The binary is not on your PATH. Re-run the "Move the binary and add shell hooks" section, or run `overwatch setup --instructions` to see the setup instructions again.

**macOS quarantine warning**
Run `xattr -d com.apple.quarantine ~/Downloads/overwatch` before running the setup wizard.

**Setup wizard skips prompts or shows garbled output on Windows**
The interactive setup wizard uses terminal escape sequences that older consoles may not support. If the wizard does not render correctly, create the config file manually at `$HOME\.method\overwatch\config.yaml` with the following content, replacing the URL with your deployment hostname:

```yaml
connection:
  method_platform_url: "yourorg.method.delivery"
tools:
  menu_color_mode: "dark"
```

**Windows blocks or removes the download**
Edge and other browsers may flag `overwatch.exe` as an uncommon download and remove it. Open the browser's downloads panel, click **Show more** or the three-dot menu next to the file, select **Keep**, then confirm you trust the file. If Windows Defender SmartScreen shows a warning when you run the binary, click **More info** and then **Run anyway**.

**Auth error on `overwatch record`**
Your binary may be out of date. Download the latest version from the platform and replace your existing binary.

**Commands not being captured in the session**
Make sure you opened a new terminal window after adding the shell hook. The hook must be active before you start a recording.

**TLS certificate errors (on-premises with self-signed certs)**
Add `insecure: true` under `connection:` in your Overwatch config file (`~/.method/overwatch/config.yaml` on macOS/Linux, `$HOME\.method\overwatch\config.yaml` on Windows):

```yaml
connection:
  method_platform_url: "yourorg.method.delivery"
  insecure: true
```