Install & Setup Guide

Dream big, build fast. This is the do-this-then-this guide for standing up AgentWatch. Follow the five steps in order; each one works on its own, and you can stop after any step and still get value. Deep-dives (MDM at scale, the DNS container, the admit webhook) are called out inside the step they belong to so you only read them when you reach them.

What AgentWatch does, in one line: it sits between your people and the AI tools they use (ChatGPT, Claude, Copilot, your API apps) so you can see usage, attribute it to a person or team, and govern content (DLP/redaction/blocking).

The install path at a glance

Step	You’ll do	Outcome
1. Decide your model	Pick hosting + how deep you inspect	A clear target before you touch anything
2. Enroll devices	Get AgentWatch onto endpoints (MDM / portal / Connect)	Traffic flows through AgentWatch
3. Attribute users	Tie traffic to a person/tenant	Usage shows who
4. Turn on content inspection	Trust the CA + enable DLP	Prompts/responses inspected, DLP enforced
5. Verify	Send a test, watch it land	Confidence it works

You do not need all five to start. Steps 1–2 already give you visibility; 3 adds who; 4 adds what + control.

---

Step 1 — Decide your model

Answer three questions first. Everything later follows from these.

1a. Where does AgentWatch run?

• Iterate-hosted (SaaS) — fastest; nothing to deploy. Best for a pilot.
• Self-hosted — you run the container in your cloud/VPC. Best for data-residency needs.

1b. How deep do you inspect? This is the single most important choice:

• Visibility only — you see which AI tools people use, volume, and timing. No prompt/response content. Requires no certificate on devices.
• Full content governance — you see prompts/responses and can redact/block (DLP). Requires the AgentWatch root CA trusted on each device (Step 4).

Rule of thumb: start with visibility to prove value in a day, then turn on content inspection for the teams that need DLP.

1c. Which AI tools? AgentWatch steers a curated set of browser AI-chat sites (chatgpt.com, claude.ai, gemini.google.com, copilot.microsoft.com, …) and governs your API apps (OpenAI-compatible). It deliberately does not touch developer/CLI tools (pip, brew, IDE agents) — those would break under inspection.

Deep-dive (only if self-hosting): see the Enterprise Guide for compose/env, TLS, and scaling.

---

Step 2 — Enroll devices

“Enroll” = get a device’s AI traffic to flow through AgentWatch. Pick the path that matches the device. You can mix paths across your fleet.

2a. Company-managed devices → MDM push (zero user effort)

Your MDM (Jamf / Intune / JumpCloud / Workspace ONE) silently pushes a profile with (1) the AgentWatch root CA and (2) a DNS profile that points AI domains at AgentWatch. The user does nothing; it works on and off the network.

1. In Admin → Enrollment Portal, download the bulk MDM profile (CA + DNS).
2. Upload it to your MDM and scope it to the right device group.
3. Done — those devices are enrolled.

Deep-dive — bulk MDM for 100–200 devices: push the one profile to a device group; use the templated Connect profile if you also want per-user identity stamped automatically (Step 3). Details in the Endpoint Enrollment Guide.

2b. Unmanaged laptops → the self-serve portal

Point the user (or your captive Wi-Fi) at your branded enrollment portal. They verify identity, then one click installs the Connect client (recommended — one install, one approval) or a configuration profile.

Deep-dive — turn the portal on: Admin → Enrollment Portal → enable + brand it (it’s off by default). See the Endpoint Enrollment Guide.

2c. The network layer → DNS

AgentWatch steers AI domains via DNS. Two options:

• Iterate-hosted resolver — point managed devices’ DoH at it. Zero infra. Good for pilots.
• Your own DNS container — run it per-tenant for auto-pop captive portal, per-tenant tuning, and org attribution by egress IP.

Deep-dive — the DNS container: run dns-server with your server URL + Connect key so it registers your egress IP for attribution (Step 3). See the Shadow-AI Onboarding guide, §“Does it need the new DNS container?”.

2d. Enforce “must enroll before AI access” (optional)

DNS only nudges; it never blocks. To require enrollment, wire the admit webhook to your NAC/Wi-Fi.

Deep-dive — admit webhook: Admin → Enrollment Portal → admit webhook URL + secret. On enrollment, AgentWatch sends your NAC an HMAC-signed callback to lift the walled garden. Sample bridge: docs/samples/agentwatch-admit-bridge.py.

---

Step 3 — Attribute users (who is this?)

Visibility is more useful when usage shows a person or team. AgentWatch attributes in this order:

1. Connect client / MDM identity — the strongest. The Connect client (or a templated MDM profile) stamps the user’s corporate email on every request. Nothing else to do if you used 2a/2b with Connect.
2. Corporate email domain → tenant — if a request’s identity is jane@acme.com, it attributes to the acme tenant automatically. Register your domain(s) in Admin → Company Settings → allowed account domains.
3. Team — assign tenants to teams to roll usage up by team in Usage Insights.
4. Custom tag (per-request) — segment by any value your app sends: add a header (e.g. x-customer-id: acme) and register it in Usage Insights → Token Usage by Custom Tag.

Personal accounts (e.g. a personal gmail on a BYOD phone) with no corporate signal attribute at the org level only, visible to the super-admin. That’s expected.

---

Step 4 — Turn on content inspection (optional but recommended)

This is where you go from “who used what” to “what did they send, and enforce policy.” It requires the root CA on the device (delivered in Step 2’s profile/Connect install).

1. Confirm the CA is trusted on a test device (the MDM/portal profile installs it). Without it, inspected sites show TLS errors — so if you skipped the CA, keep those sites in visibility-only mode.
2. Enable DLP in Admin → Company Settings: choose redact (mask PII in place) or block (refuse the request), and turn on the scanners you need (PII, financial/PCI, health/HIPAA, secrets, guardrails for injection/toxicity).
3. Set your email sender so DLP alarms and enrollment OTPs come from your domain (Settings → Email Notifications — SMTP/SendGrid/SES or Google Workspace).

Browsers ship their own “Secure DNS” that bypasses the system resolver. The AgentWatch profile already disables it for Chrome/Edge; if you configure DNS by hand, push a “Secure DNS = off” browser policy too.

---

Step 5 — Verify

1. On an enrolled device, open chatgpt.com and send a normal message. In Usage Insights → Full Audit Trail, you should see the request within a few seconds, attributed to the user/tenant, status Completed.
2. Test DLP (if enabled): send a message containing a fake SSN (e.g. 123-45-6789). It should come back Redacted or Blocked, and the stored preview must show a placeholder — never the raw value.
3. Test attribution: confirm the row shows the right person/tenant (or your custom tag value).

If a row doesn’t appear or attribution looks wrong, see Troubleshooting (docs/TROUBLESHOOTING.md) — it covers the common causes (CA not trusted, browser Secure-DNS on, personal vs corporate identity).

---

Where to go deeper

Topic	Guide
Endpoint enrollment (MDM, portal, Connect) in depth	AgentWatch_Endpoint_Enrollment_Guide
Shadow-AI end-to-end + the DNS-container decision	AgentWatch_Shadow_AI_Onboarding
Gateway routes / tenant modes	AgentWatch_Gateway_Rules_Config
SSO (SAML/OIDC)	AgentWatch_SAML_SSO_Setup
Everything (reference)	AgentWatch_User_Guide, AgentWatch_Enterprise_Guide

---

_{© Iterate.ai · AgentWatch · Dream big, build fast.}