Windows Setup Guide

This guide covers installing and configuring onWatch on Windows. Choose between the one-click installer (recommended) or manual setup for full control.

Option 1: One-Click Installer (Recommended)

The PowerShell installer handles everything automatically: downloading the binary, configuring providers, creating the .env file, and adding onWatch to your PATH.

Method A: PowerShell Command

Open PowerShell and run:

irm https://raw.githubusercontent.com/onllm-dev/onwatch/main/install.ps1 | iex

Method B: Download install.bat

Download install.bat from the Releases page
Double-click install.bat
Follow the interactive prompts

The installer will:

Download the Windows binary to %USERPROFILE%\.onwatch\bin\
Auto-detect Claude Code and Codex tokens if available
Guide you through configuring API providers
Create dashboard credentials
Create the .env configuration file
Add onWatch to your user PATH
Start onWatch in the background

Option 2: Manual Setup

If you prefer full control or the installer doesn't work for your environment, follow these steps.

Step 1: Download the Binary

Go to the Releases page
Download onwatch-windows-amd64.exe
Create the installation directory:

mkdir "$env:USERPROFILE\.onwatch\bin" -Force
mkdir "$env:USERPROFILE\.onwatch\data" -Force

Move the binary:

Move-Item onwatch-windows-amd64.exe "$env:USERPROFILE\.onwatch\bin\onwatch.exe"

Step 2: Create the Configuration File

Create a .env file at %USERPROFILE%\.onwatch\.env with your API keys.

Using PowerShell:

@"
# onWatch Configuration

# At least one provider is required. Uncomment and configure the ones you use.

# Synthetic API key (https://synthetic.new/settings/api)
# SYNTHETIC_API_KEY=syn_your_key_here

# Z.ai API key (https://www.z.ai/api-keys)
# ZAI_API_KEY=your_key_here
# ZAI_BASE_URL=https://api.z.ai/api

# Anthropic token (Claude Code - see "Retrieving Tokens" below)
# ANTHROPIC_TOKEN=your_token_here

# Codex OAuth token (see "Retrieving Tokens" below)
# CODEX_TOKEN=your_token_here

# GitHub Copilot PAT with copilot scope
# COPILOT_TOKEN=ghp_your_token_here

# Antigravity (Windsurf) - auto-detected from local process
# ANTIGRAVITY_ENABLED=true

# Dashboard credentials
ONWATCH_ADMIN_USER=admin
ONWATCH_ADMIN_PASS=changeme

# Polling interval in seconds (10-3600)
ONWATCH_POLL_INTERVAL=120

# Dashboard port
ONWATCH_PORT=9211
"@ | Set-Content "$env:USERPROFILE\.onwatch\.env"

Or using Notepad:

notepad "$env:USERPROFILE\.onwatch\.env"

Then paste the configuration above and save.

Step 3: Configure Providers (Optional at Startup)

onWatch can start with no providers configured. You can enable providers later in Settings -> Providers.

If you want to pre-configure providers in .env, set any of the following:

Synthetic

SYNTHETIC_API_KEY=syn_your_key_here

Get your key at: https://synthetic.new/settings/api

Z.ai

ZAI_API_KEY=your_key_here
ZAI_BASE_URL=https://api.z.ai/api

Get your key at: https://www.z.ai/api-keys

Anthropic (Claude Code)

ANTHROPIC_TOKEN=your_token_here

See Retrieving Anthropic Token below.

Codex

CODEX_TOKEN=your_token_here

See Retrieving Codex Token below.

GitHub Copilot

COPILOT_TOKEN=ghp_your_token_here

Create a Personal Access Token (classic) with copilot scope at: https://github.com/settings/tokens

Antigravity (Windsurf)

ANTIGRAVITY_ENABLED=true

Requires Windsurf to be running. onWatch auto-detects the local server.

Step 4: Add to PATH (Optional)

Add onWatch to your user PATH for easy access:

$path = [Environment]::GetEnvironmentVariable("Path", "User")
$onwatchPath = "$env:USERPROFILE\.onwatch"
if ($path -notlike "*$onwatchPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$onwatchPath;$path", "User")
}

Restart your terminal for PATH changes to take effect.

Step 5: Run onWatch

Navigate to the installation directory and run:

cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe

Or if you added it to PATH:

onwatch

Open your browser to http://localhost:9211 and log in with your configured credentials.

Retrieving Tokens

Retrieving Anthropic Token

If you have Claude Code installed, your token is stored in the credentials file:

(Get-Content "$env:USERPROFILE\.claude\.credentials.json" | ConvertFrom-Json).claudeAiOauth.accessToken

Copy the output and paste it as ANTHROPIC_TOKEN in your .env file.

Retrieving Codex Token

If you have Codex CLI installed, your token is stored in the auth file:

(Get-Content "$env:USERPROFILE\.codex\auth.json" | ConvertFrom-Json).tokens.access_token

If you use a custom CODEX_HOME:

(Get-Content "$env:CODEX_HOME\auth.json" | ConvertFrom-Json).tokens.access_token

Copy the output and paste it as CODEX_TOKEN in your .env file.

Running onWatch

Start (Background)

cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe

onWatch runs in the background. Access the dashboard at http://localhost:9211.

Start (Foreground/Debug)

cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe --debug

Logs are printed to the console. Useful for troubleshooting.

Stop

cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe stop

Check Status

cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe status

Creating a Desktop Shortcut

To create a shortcut for easy access:

Right-click on your Desktop
Select New > Shortcut
Enter the location:
```
%USERPROFILE%\.onwatch\bin\onwatch.exe
```
Click Next and name it "onWatch"
Click Finish

To run in debug mode (shows console window):

Right-click the shortcut > Properties

In Target, append --debug:

%USERPROFILE%\.onwatch\bin\onwatch.exe --debug

Running as a Windows Service (Advanced)

For production deployments, you can run onWatch as a Windows Service using NSSM (Non-Sucking Service Manager):

Download NSSM from https://nssm.cc/download
Extract and open Command Prompt as Administrator
Install the service:

nssm install onwatch "%USERPROFILE%\.onwatch\bin\onwatch.exe"
nssm set onwatch AppDirectory "%USERPROFILE%\.onwatch"
nssm set onwatch AppParameters "--debug"
nssm set onwatch DisplayName "onWatch API Quota Tracker"
nssm set onwatch Description "Tracks AI API quota usage"
nssm set onwatch Start SERVICE_AUTO_START
nssm start onwatch

Manage the service:

nssm status onwatch
nssm stop onwatch
nssm restart onwatch
nssm remove onwatch confirm

Troubleshooting

Windows Defender False Positive

Windows Defender may flag onwatch.exe as Program:Win32/Wacapew.A!ml. This is a false positive.

Why this happens: Go binaries are statically compiled, bundling the entire runtime into a single ~15MB executable. This structure - combined with the binary's network operations (HTTP server, API polling) - triggers machine learning heuristics designed to detect packed or obfuscated malware. This is a known issue affecting many legitimate Go applications.

Our status: We have submitted onwatch.exe to Microsoft for analysis and whitelisting. This process typically takes 1-2 weeks.

Workaround: Add an exclusion in Windows Defender:

Open Windows Security → Virus & threat protection
Under "Virus & threat protection settings", click Manage settings
Scroll to Exclusions → Add or remove exclusions
Click Add an exclusion → Folder
Add: C:\Users\<your-username>\.onwatch

The source code is fully auditable at github.com/onllm-dev/onwatch (GPL-3.0).

"No provider data appears in dashboard"

If the app starts but no quota cards update:

Ensure .env exists at %USERPROFILE%\.onwatch\.env
Configure a provider key (or use auto-detect providers)
Open Settings -> Providers and enable telemetry for that provider
Restart or click provider reload in Settings

Binary Flashes and Closes Immediately

This happens when double-clicking the binary without configuration. Either:

Use the one-click installer: irm https://raw.githubusercontent.com/onllm-dev/onwatch/main/install.ps1 | iex
Follow the manual setup steps above

Port Already in Use

If port 9211 is taken, change it in .env:

ONWATCH_PORT=9212

Check what's using a port:

netstat -ano | findstr :9211

Cannot Find onwatch Command

If onwatch isn't recognized after adding to PATH:

Restart your terminal/PowerShell
Or use the full path: $env:USERPROFILE\.onwatch\bin\onwatch.exe

Token Auto-Detection Not Working

If Claude Code or Codex tokens aren't auto-detected:

Ensure the respective tool is installed and you've logged in
Check that credential files exist:
- Claude Code: %USERPROFILE%\.claude\.credentials.json
- Codex: %USERPROFILE%\.codex\auth.json
Manually retrieve and paste the token (see Retrieving Tokens)

Updating onWatch

Using Self-Update

cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe update

Manual Update

Stop onWatch: .\bin\onwatch.exe stop
Download the new binary from Releases
Replace %USERPROFILE%\.onwatch\bin\onwatch.exe
Start onWatch: .\bin\onwatch.exe

Uninstalling

To completely remove onWatch:

# Stop onWatch
cd "$env:USERPROFILE\.onwatch"
.\bin\onwatch.exe stop

# Remove installation directory
Remove-Item -Recurse -Force "$env:USERPROFILE\.onwatch"

# Remove from PATH (optional)
$path = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = ($path -split ';' | Where-Object { $_ -notlike "*\.onwatch*" }) -join ';'
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")

Support

MiniMax

MINIMAX_API_KEY=sk-cp_your_key_here

Get your key at: https://platform.minimax.io

FilesExpand file tree

WINDOWS_SETUP.md

Latest commit

History