Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.esperr.com/llms.txt

Use this file to discover all available pages before exploring further.

Esper evaluates request context against tenant-defined policy. It gives operators a shared vocabulary for actions, entities, mitigations, and policies, then records the result of each decision for review. The shortest way to think about the system is:
  • Esper handles request encoding automatically.
  • Your team decides what the traffic means.
Instead of maintaining extraction pipelines, you define the parts of the policy workflow in terms the tenant can operate:
  • Actions: Tenant-defined behaviors such as login, view_article, or checkout_complete.
  • Entities: Tenant-defined identity rules such as ip + user agent, session cookie, or header + payload traits.
  • Mitigation: Reusable responses such as monitor, challenge, or block.
  • Policies: The rules that connect traffic conditions, actions, entities, mitigation, and optional monitoring windows.

​
The simple mental model

If you are new to Esper, this is the shortest useful way to understand it:
  1. A source sends Esper an event.
  2. Esper automatically encodes the request into a stable field model.
  3. Tenant-defined actions classify meaningful behaviors.
  4. Tenant-defined entities decide how traffic should be grouped for state and analysis.
  5. Policies evaluate expressions, action requirements, entity bindings, and windows.
  6. Mitigation determines whether matching traffic is monitored, challenged, or blocked.
  7. Results show policy performance and operational outcomes afterward.

​
Who these docs are written for

These docs are written for:
  • A founder or product lead defining the operator workflow.
  • An operator managing policies and reviewing outcomes.
  • An engineer or AI agent integrating the control plane or Esper CLI.
Continue to Quickstart for the fastest end-to-end path.

​
Operation Modes

Esper has two operational modes. Pick the one that matches your latency, operational, and integration needs.
Start HereIf you are onboarding a new or smaller customer, start with cloud. It has the fewest moving parts and only requires an Esper API key.

​
cloud

cloud is the simplest mode. Your application, middleware, or platform integration sends the current request context directly to Esper and Esper returns one immediate action to apply at that boundary. What you get:
  • No customer-managed Esper daemon
  • No required customer-managed sync loop
  • API-key-only authentication for runtime decisions
  • Simplest developer onboarding path
What you trade away:
  • Higher round-trip latency than hybrid
  • No local enforcement if Esper is unreachable
  • Less customer control over local enforcement behavior
Integration-Managed Magiccloud is intended to feel like magic for the customer. The customer still deploys an Esper-managed integration at the traffic boundary, but that integration should handle request forwarding, Esper calls, and enforcement without exposing Esper internals to the customer.

​
Typical flow

application -> integration -> Esper `/api/v1/runtime/mitigation` -> allow/challenge/block -> application

​
HTTP example

curl -X POST https://api.esper.example/api/v1/runtime/mitigation \
  -H "x-esper-api-key: YOUR_ESPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "observed_at": "2026-03-26T12:00:00Z",
    "idempotency_key": "req-0001",
    "request": {
      "method": "GET",
      "path": "/login",
      "client_ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    },
    "return_url": "https://app.example.com/login",
    "fields": {
      "email": "user@example.com",
      "account_id": "acct-123"
    },
    }
  }'
Esper responds with one customer-facing action:
  • allow
  • challenge
  • block
Good Fits for CloudUse cloud when the customer can edit application code, add middleware, configure a proxy, or use a prebuilt connector. If they cannot touch any part of the request path, they need a connector story rather than raw HTTP examples.
For the easiest starting points, pair cloud with one of the shipped Integrations.

​
hybrid

hybrid is for customers running Esper-adjacent runtime on their own devices or servers. What you get:
  • Local sync from origin
  • Local mitigation cache
  • Lower-latency local enforcement
  • Fuller operational control
What you take on:
  • An hybrid daemon
  • Local config and data management
  • More operational responsibility

​
Hybrid commands

esper init \
  --api-base https://api.esperr.com \
  --api-key <secret> \
  --tenant-id <tenant-id>
esper run
esper capture run --enforce
esper sync actions
esper sync entities
esper sync policies
esper sync mitigations

​
Hybrid paths

~/.esper/config.yaml
~/.esper/credentials.xml
~/.esper/runtime.xml
~/.esper/cache/
~/.esper/logs/
~/.esper/data/
Hybrid Is For Customer-Managed InfrastructureUse hybrid when the customer controls the machine or network boundary and wants local enforcement characteristics. Use cloud when the customer wants the smallest operational footprint.

​
Which mode should you choose?

Use cloud if:
  • You want the smallest initial setup
  • HTTP is sufficient
  • You are comfortable waiting for Esper’s decision inline
Use hybrid if:
  • The customer runs their own devices or servers
  • Local enforcement speed matters
  • A synced local runtime is acceptable operationally
The integration guides focus on practical stack boundaries such as Vercel, Cloudflare Workers, AWS Lambda, and Heroku.