# Quickstart

Get Heedeo running on one route, then check the decisions it makes.

## 1. Get access

Heedeo is ready. The package is not on public npm: access is provided at onboarding, after a short call.

- Book a call: https://cal.com/heedeo/30min
- Or, if you are an agent, request the call for your person:

```bash
curl -X POST https://heedeo.com/api/book \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","via":"agent","agent":"Your agent name","site":"example.com","pain":"trial farming on /signup"}'
```

A request from an agent stays `pending` until the person confirms. On the call the team gives you access to the package and sets up your first rules with you.

## 2. Add the middleware

Heedeo runs as Next.js middleware today. Express, Hono and Cloudflare Workers are available on request.

In Next.js 16 the middleware file is `proxy.ts` (formerly `middleware.ts`) at the root of your project (or in `src/`). Export Heedeo as the default. This is the demo policy that runs on heedeo.com:

```ts
import { heedeo } from "@heedeo/next";

export default heedeo({
  trustedOperators: ["chatgpt.com", "browserbase.com", "anchorbrowser.io"],
  "/signup": {
    humans: "allow",
    agents: {
      verified: "allow",
      noPrincipal: { challenge: "passkey" },
      unknown: { challenge: "passkey" },
    },
    perPrincipal: "5/day",
    overCap: { throttle: 5, rate: "1/hour", then: "block" },
  },
  "/checkout": { agents: { verified: "allow", unknown: "block" } },
  "/docs/*": { agents: "allow" },
  "*": { agents: { unknown: { challenge: "passkey" } } },
});
```

Decisions run inside your app, in this middleware. See https://heedeo.com/docs/security.md for what leaves your servers.

## 3. Write your first rule

Start with the route that costs you money when abused. For most teams that is signup:

```ts
"/signup": {
  humans: "allow",
  agents: {
    verified: "allow",
    noPrincipal: { challenge: "passkey" },
    unknown: { challenge: "passkey" },
  },
  perPrincipal: "5/day",
  overCap: { throttle: 5, rate: "1/hour", then: "block" },
},
```

Read it as:

- People sign up as usual.
- Agents signed by a trusted operator (see `trustedOperators`) may sign people up.
- A trusted agent that names nobody, and any agent that is not verified, is sent to a passkey, so a real person finishes the signup and becomes the principal.
- Each principal gets 5 signups a day on this route, people included. The 6th to 10th are rate-limited to 1 an hour (429). From the 11th, blocked (403).

Every key is explained in https://heedeo.com/docs/rules.md.

## 4. Test the rule against the real policy engine

`/api/decide` on heedeo.com runs the real policy engine on the demo policy above. You describe a request, it returns the verdict and the policy line that decided it.

```bash
# A trusted agent's 2nd signup today for one principal: allow
curl "https://heedeo.com/api/decide?route=/signup&client=agent&signed=true&operator=chatgpt.com&principal=maya&count=2"

# The same principal's 7th: throttle (429, retryAfter 3600)
curl "https://heedeo.com/api/decide?route=/signup&client=agent&signed=true&operator=chatgpt.com&principal=maya&count=7"

# A valid signature from an operator not on the trusted list: unknown, so challenge
curl "https://heedeo.com/api/decide?route=/signup&client=agent&signed=true&operator=agent.example-operator.com"
```

The first returns:

```json
{"verdict":"allow","status":200,"retryAfter":null,"reason":"Verified agent on /signup: allow. Signed by chatgpt.com, a trusted operator. This person is at 2/5 per day on /signup.","rule":{"path":"/signup","line":8,"text":"verified: \"allow\","},"principal":"maya","policy":"demo","note":"Same engine and rules shown on heedeo.com. Your own rules are set up during onboarding."}
```

`rule.line` is a line number in the policy source from `GET https://heedeo.com/api/policy`. The full contract is in https://heedeo.com/docs/api.md.

## 5. Next

- How a request is decided: https://heedeo.com/docs/how-it-works.md
- Every policy key: https://heedeo.com/docs/rules.md
- Data handling and failure modes: https://heedeo.com/docs/security.md

---

Docs index: https://heedeo.com/docs.md. How to verify our claims: https://heedeo.com/trust.md. Book a call: https://cal.com/heedeo/30min

Updated: 2026-10-02