# Agents Overwatch: agent setup

You are being connected to Agents Overwatch, a dashboard where your user sees what each of their agents is doing.
Follow these steps exactly.  Never print, echo or log your agent key, and never paste it into the chat.

## 1. Get the setup token

Ask your user: "Paste your Agents Overwatch setup token."  They make it on the dashboard (Setup, then the agent's
**New token**).  It starts with `aow_setup_`, works once, and expires 15 minutes after it was made.

## 2. Swap it for your own key

Run the command for your system, with the token in place of `PASTE_TOKEN_HERE` and your name (as your user knows you)
in place of `YOUR_NAME`.  It writes your key straight to a file only your user account can read, one file per agent
(other agents on this computer have their own), and prints only where it saved it, e.g.
`saved ~/.agents-overwatch/3f2a....json`.  That path is your KEY_FILE below.

macOS or Linux:

```sh
mkdir -p ~/.agents-overwatch && chmod 700 ~/.agents-overwatch
curl -fsS https://aow-staging.onrender.com/v1/setup/exchange -H 'content-type: application/json' \
  -d '{"setup_token": "PASTE_TOKEN_HERE", "label": "YOUR_NAME"}' \
| python3 -c 'import json,os,sys; r=json.load(sys.stdin); n="~/.agents-overwatch/"+r["agent_id"]+".json"; fd=os.open(os.path.expanduser(n), os.O_WRONLY|os.O_CREAT|os.O_TRUNC, 0o600); os.write(fd, json.dumps({"api": "https://aow-staging.onrender.com", "agent_key": r["agent_key"]}).encode()); os.close(fd); print("saved", n)'
```

Windows (PowerShell):

```powershell
$dir = Join-Path $HOME ".agents-overwatch"; New-Item -ItemType Directory -Force $dir | Out-Null
$r = Invoke-RestMethod -Method Post -Uri "https://aow-staging.onrender.com/v1/setup/exchange" -ContentType "application/json" `
  -Body (@{setup_token = "PASTE_TOKEN_HERE"; label = "YOUR_NAME"} | ConvertTo-Json)
$file = Join-Path $dir "$($r.agent_id).json"
@{api = "https://aow-staging.onrender.com"; agent_key = $r.agent_key} | ConvertTo-Json -Compress | Set-Content -Encoding ascii $file
icacls $file /inheritance:r /grant:r "$($env:USERNAME):(R,W)" | Out-Null; Remove-Variable r; "saved $file"
```

If it fails with "bad_setup_token", the token was wrong, used or expired: ask your user for a new one.

## 3. Confirm

Put your KEY_FILE in place of `KEY_FILE`.

macOS or Linux:

```sh
python3 -c 'import json,os,urllib.request; c=json.load(open(os.path.expanduser("KEY_FILE"))); r=urllib.request.Request(c["api"]+"/v1/whoami", headers={"Authorization": "Bearer "+c["agent_key"]}); print(urllib.request.urlopen(r).read().decode())'
```

Windows (PowerShell):

```powershell
$c = Get-Content "KEY_FILE" | ConvertFrom-Json
Invoke-RestMethod -Uri "$($c.api)/v1/whoami" -Headers @{Authorization = "Bearer $($c.agent_key)"}; Remove-Variable c
```

You should see your workspace, project, machine and your name.  Tell your user setup worked.

## 4. Remember how to report

Add this to your standing instructions (CLAUDE.md, AGENTS.md or similar), with your KEY_FILE filled in, so you keep
doing it in later sessions:

> Agents Overwatch: my key is in KEY_FILE (read it from there each time; never print it).  Send
> POST https://aow-staging.onrender.com/v1/heartbeat with {"state": "working" | "idle" | "waiting" | "error" | "off", "task": "one line"}
> when my state changes and at least every minute while working; "waiting" when I need my user.  For development
> work, POST https://aow-staging.onrender.com/v1/plans/<plan-id>/checkins with the full phase list first, then only what changed, and "now"
> saying where I'm at.  GET https://aow-staging.onrender.com/v1/plans/<plan-id> to join a plan another agent started.

## Reporting through MCP instead

If you support remote MCP servers, your user can add this server instead of you calling the API directly.  It has
the tools report_status, checkin_plan, get_plan and list_plans:

```json
{"mcpServers": {"agents-overwatch": {"type": "http", "url": "https://aow-staging.onrender.com/mcp",
  "headers": {"Authorization": "Bearer ${AGENTS_OVERWATCH_KEY}"}}}}
```