Overwatch

Run an Overwatch session

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

Download the binary

In the platform, navigate to Reaper and start a new session:

  1. Click New Overwatch session to create a new session
  2. Input a name for the session, select the target environment, then click Create Session
  3. On the Overwatch session page, click the information icon and download the binary under “Download Overwatch Binary”
OSArchitectureChoose
macOSApple Silicon (M1/M2/M3)macOS ARM64
macOSIntelmacOS 64-bit
Linuxx86_64Linux 64-bit
LinuxARM64Linux ARM64

Make the binary executable

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

Run the setup wizard

$~/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.

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:

$mv ~/Downloads/overwatch ~/.local/bin/overwatch

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

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

Then add the Overwatch shell hook for your shell:

zsh:

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

bash:

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

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

$overwatch --version

Start a recording

In your new terminal window, run:

$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

$# 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:

OptionDescription
Pause RecordingStops capturing commands. The status bar turns yellow to indicate the session is paused.
Resume RecordingResumes capturing after a pause.
Stop RecordingImmediately exits Overwatch and kills the terminal session.
Magic InputsOpens 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.

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:

1connection:
2  method_platform_url: "yourorg.method.delivery"
3tools:
4  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):

1connection:
2  method_platform_url: "yourorg.method.delivery"
3  insecure: true