> ## 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.

# Overview

> Esper evaluates request context with tenant-defined actions, entities, mitigations, and policies.

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](./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.

<Tip>
  **Start Here**

  If you are onboarding a new or smaller customer, start with `cloud`.
  It has the fewest moving parts and only requires an Esper API key.
</Tip>

### `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

<Info>
  **Integration-Managed Magic**

  `cloud` 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.
</Info>

#### Typical flow

```text theme={null}
application -> integration -> Esper `/api/v1/runtime/mitigation` -> allow/challenge/block -> application
```

#### HTTP example

```bash theme={null}
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`

<Tip>
  **Good Fits for Cloud**

  Use `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.
</Tip>

For the easiest starting points, pair `cloud` with one of the shipped
[Integrations](./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

```bash theme={null}
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

```text theme={null}
~/.esper/config.yaml
~/.esper/credentials.xml
~/.esper/runtime.xml
~/.esper/cache/
~/.esper/logs/
~/.esper/data/
```

<Tip>
  **Hybrid Is For Customer-Managed Infrastructure**

  Use `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.
</Tip>

### 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

<Info>
  The integration guides focus on practical stack boundaries such as Vercel,
  Cloudflare Workers, AWS Lambda, and Heroku.
</Info>