# Install Wake

> Three steps: prove you own the host, deploy the collector on your edge or server, watch the first event land. Nothing runs in the browser except, on Express, one optional script tag that tells people apart from headless browsers.

## 0 · Or hand the whole thing to your AI

Open your desk → **Install**. Step 1 has **Hand it to your AI**: one block of instructions with the ownership tag, where it goes on your stack, and the check. Step 2, option B, writes **`wake-playbook.md`** from a deep scan of the public site (how it answers GPTBot, ClaudeBot, PerplexityBot and a scripted client; the stack; llms.txt, agent card, MCP server card, OpenAPI; the site's shape by page class; docs without JavaScript; Markdown negotiation): every change the scan calls for, with the exact files generated from your own pages, where they go on your stack, the collector for your stack with its key once ownership is confirmed, and a curl to verify each step. Save it in the repository and tell Claude Code, Cursor or Codex to complete every task in it. Also: `wake playbook --out wake-playbook.md`, `GET /api/wake/v1/playbook.md`, or the MCP tool `wake_playbook`.

## 1 · Ownership

Open your desk → **Install → step 1**. Add one of:

- **Meta tag (preferred)**: `<meta name="wake-verify" content="…">` in the `<head>` of the homepage, or
- **Well-known file**: `https://<host>/.well-known/wake-verify.txt` with the body shown, or
- **DNS record**: a TXT record at `_wake-verify.<host>` with the value shown.

Wake checks every 30 seconds while the page is open (for up to four hours, then **Check now** starts another four) and the step turns green on its own; **Check now** checks at once. Any one method proves control of the host; nothing else is read. Ownership gates the collector keys, the readiness report and the listing plan.

The check follows one redirect when it stays on the same site (apex ↔ www) and names itself with the user-agent `WakeVerify/0.1`. When it fails, the screen says why per method: the homepage redirects to another host (add that host as the site), the site answered 403 (allow `WakeVerify` in the WAF or bot rules, or use the DNS record), a tag with another token is on the page (copy the tag again), a TXT record exists with another value.

## 2 · Collector

Press **Generate the file**. You get, once, an ingest key and deploy-ready files that already carry it:

| File | Where it runs |
|---|---|
| `cloudflare-worker.js` + `wrangler.toml` | A Cloudflare Worker route in front of your origin (recommended in front of any stack, hosted builders included; zero latency, `waitUntil`). Fill in the route in `wrangler.toml`. |
| `express.js` | Express / Connect middleware on Node ≥ 18. |
| `nextjs-middleware.js` | Next.js `middleware.ts` on the Edge runtime (`proxy.ts` on Next.js 16), plus `withAxo()` on the route handlers agents call. |

The desk opens the files again any time (**Open the files**) as long as the kit was minted after kits were kept; older collectors need **Rotate keys**. The ingest endpoint chosen when the kit was minted is reused when it is reopened, so a reopened file points where the deployed one does. The read key shown with the kit is read access for the API and MCP server; the collector does not need it.

What the collector sends, per agent request: timestamp, method, **page class**, status code, the user-agent (sent for classification and never stored), a country code if your platform provides one, the **network operator** of the address block (the ASN name, such as Amazon or Google, which the Cloudflare collector reads from the edge), and an **opaque per-agent hint** computed from the client address with **your** site secret. The raw IP never leaves your infrastructure. No query string, body, cookie or referrer is ever sent. Prefetch and prerender requests (`Sec-Purpose: prefetch`) are skipped. Wake's own checks carry a keyed `x-wake-probe` header (an HMAC of the UTC day under your ingest key hash) and are never counted; a bare header value does nothing.

Status codes are what make the friction screens work. The Cloudflare Worker and the Express middleware see every response status. Next.js middleware runs before the route and cannot, so its events carry status 0 ("reached"). **The Next.js middleware does not report api, auth, account or checkout requests at all**: wrap those route handlers with the `withAxo()` export from the same file (`import { withAxo } from "@/middleware"`; `@/proxy` on Next.js 16) and their real 401s, 404s and 5xx reach the desk. Without it, those requests are invisible. `withAxo()` reports through `after()` on Next.js 15+, through `waitUntil` where the runtime passes one, and otherwise awaits the send with a 1.5 s cap.

Secrets: each file reads `AXO_SITE_SECRET` (and `AXO_INGEST_KEY`) from the environment first and falls back to the literal inside it, so it can live in a shared repository. On Cloudflare: `wrangler secret put AXO_SITE_SECRET`.

### Express behind a proxy

Behind Railway, Render, Fly, Heroku or any load balancer, the socket address is the proxy's. Tell Express to trust it, before the collector:

```js
app.set("trust proxy", 1);
app.use(axoCollector);
```

The generated file reads the country from `cf-ipcountry`, `x-vercel-ip-country` or `x-country-code`, and the client address from `req.ip`. Both are options of `axoExpressMiddleware`, for a proxy that uses other headers:

```js
axoExpressMiddleware({
  endpoint, ingestKey, siteSecret,
  country: (req) => req.headers["x-my-country"] || "",
  clientIp: (req) => req.headers["x-real-ip"] || req.ip || "",
});
```

A Cloudflare Worker from the same kit in front of an Express collector marks the requests it already reported (`x-wake-collected: 1`); the middleware skips them, so nothing is counted twice.

You can also fetch the kit from a terminal once a key exists ([CLI](/wake/docs/cli)):

```bash
wake install --kit --out ./wake-collector
```

**Rotate keys** mints a new ingest key and site secret; the deployed collector stops until you redeploy, and nicknames restart. The desk says so while no event has arrived since the rotation.

## 3 · First event

The Install screen checks every 10 seconds. Wake never sends test traffic on your behalf: a real agent, or one request you make as an agent after the deploy, produces the first event:

```bash
curl -s -o /dev/null -A "WakeFirstEvent/1.0" https://<host>/
```

It appears as an undeclared likely agent (a non-browser user-agent with no operator family). From then on **Overview** leads with the agents that came, what they did, and what to add to the site so they can navigate it. A desk that has reported once stays live through a quiet week: step 3 shows the first event and says that nothing arrived in the last 7 days.

## The human tell · agent or human, as a percentage

Agents never run page scripts; people scroll, move a pointer, type. Add one line to your HTML layout (Express collector today):

```html
<script src="/__wake/i.js" defer></script>
```

The collector serves that script itself. A page that reports a person (pointer, scroll, keys or touch, with a small proof-of-work the page had to compute) is dropped on your server: nothing about the person is sent. A browser-looking page view that stays silent for ten seconds goes out as a headless suspect. The script also measures how the pointer and the wheel move during the first second after the first interaction, on the page, and sends only a few bucketed numbers (straightness, speed variation, timing regularity, teleport jumps, micro-corrections, wheel burst pattern), never a coordinate: interpolated movement, the way Playwright, Puppeteer and Selenium drive a mouse, is flagged as scripted and the page view goes out as an agent; a hand's movement strengthens the person verdict. Every session on the desk then carries a certainty, **Agent 96%** or **Human 93%** or **Unsure**, with the evidence beside it: identity (a verified Web Bot Auth signature, a declared operator, a non-browser user agent), fingerprint (what every browser sends, the protocol, a cloud address block), behaviour (bursts, strafing, machine-only trails, metronome timing) and the human tell. Nothing identifying is stored at any point.

## Connect your AI

Under **Connect your AI** mint an API key and paste one snippet into Claude Code, Cursor, Codex or Claude Desktop. Your assistant can then ask the desk what agents did and what to fix, directly. See [MCP](/wake/docs/mcp) and [API](/wake/docs/api).

## Troubleshooting

- **401 from the ingest endpoint**: the ingest key was rotated; redeploy with the new file.
- **No events but agents visit**: check the route covers the paths agents hit (docs, API); the Worker template matches the agent user-agent list and `Sec-Fetch` signals, not browsers. On Next.js, api/auth/account/checkout need `withAxo()`.
- **Ownership check answers 403**: a WAF or bot rule blocks `WakeVerify/0.1`; allow that user-agent or use the DNS record.
- **"Could not read the collector state just now"**: the desk could not read the site record or the edge; try again in a minute. The Generate button is withheld rather than minting a key twice.
- **Readiness says agents cannot fetch the homepage**: the first HTTPS request returned a challenge or a non-200. Serve a plain 200 with HTML or Markdown for named AI clients.


## Send agent events to PostHog

If your product analytics live in PostHog, connect your project under **Connect your AI → Destinations**. Every fifteen minutes the desk forwards each agent request as an `agent_request` event and each closed visit as an `agent_session` event (stage, task, friction, conversion, threat level), in PostHog's batch capture format, with `$geoip_disable` and no person profiles. Filter on `wake_site` in PostHog; a funnel of `agent_request` by `page_class` shows the same path the desk shows.


## Which of your accounts the agent acted for

PostHog identifies people with `identify()`; Wake does the agent edition on your server, where you already know who authenticated. In your auth code, name the account on the response: Express `res.locals.axoAccount = user.id` (or the header `x-axo-account: <user id>`); Next.js and Cloudflare: set the response header `x-axo-account`. The collector hashes it with your site secret and strips the header, so the desk groups sessions by account (Agents → "Acting for your accounts", the session detail, the `account` dimension in Explore) and never sees the id. Match the hash on your side when you need to know who.

## Let your AI do the whole install

Give your coding agent an API key from Connect your AI and this prompt:

> Set up Wake for this repository. Call `wake_me` to learn the host. Call `wake_verify`; if it is not verified, place the meta tag it returns in the homepage head, deploy, and call `wake_verify` again until it passes. Then call `wake_provision`, write the file for this stack where its README says (Cloudflare Worker route with its wrangler.toml, Express middleware with `app.set("trust proxy", 1)` and the `/__wake/i.js` script tag in the layout, or Next.js `middleware.ts` / `proxy.ts` plus `withAxo` on the api, auth, account and checkout handlers), set `x-axo-account` in the auth code, deploy, then make one request with the user-agent `WakeFirstEvent/1.0` and call `wake_health` until it reports the event. Report what you changed.
