# Static response cache

> **Cache mode is opt-in.** Add a valid `_cache-...` suffix to the proxy **password** to activate it. The suffix is the complete opt-in: no account-level activation or token allowlist is needed. Without it, Litport does not intercept or cache anything: ordinary proxy behavior is unchanged. Certificate handling is required only for cache mode.

## Practical uses

Cache is most useful when many workers revisit public pages that share the same versioned assets.
Browser automation and repeated crawls can reuse images, fonts, CSS, and JavaScript from one hub
instead of buying the same response bytes for every worker.

### Measured example: 1,000 ticket-page visits

```docs-figure
cache-savings-example
Measured example from a clean anonymous StubHub homepage load; static assets change over time.
```

This counts decoded response bodies only. Bypasses, expiry, eviction, hub changes, and your actual
rate affect results; unlimited plans show free bytes but do not receive a cash credit.

## Where cache works

Cache mode is available on every Litport customer product family: datacenter, ISP/static residential,
residential, mobile, unlimited, and pay-per-GB. Every cache-enabled request through the HTTP proxy
endpoint is evaluated. Eligible static HTTPS `GET` requests may store or hit; ineligible requests
bypass through the ordinary proxy path. SOCKS5 ingress never caches.

```docs-figure
cache-compatibility
Cache eligibility depends on activation, ingress, target protocol, and request safety.
```

## Quickstart

1. [Download and trust the Litport cache root](/docs/proxy-cache/certificate), or use that page's
   isolated verification-skip option for public-data automation.
2. Add `_cache-scripts` to the **proxy password**.
3. Request the same eligible HTTPS URL twice through `hub-us-7.litport.net`.
4. Open Traffic statistics to see the miss, hit, free bytes, and pay-per-GB savings.

```bash
# Proxy endpoint: http://hub-us-7.litport.net:PORT · Target: pinned Lodash on jsDelivr
curl --proxy 'http://hub-us-7.litport.net:PORT' \
  --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert litport-cache-root.crt \
  'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js'
```

The proxy URL starts with `http://` because curl uses HTTP CONNECT to reach Litport. That does not
make the target plain HTTP: the URL at the end must start with `https://`.

```docs-figure
cache-cold-warm
Cold requests reach a verified HTTPS origin and are billed normally. A repeat hit at the same Litport hub is served locally, opens no upstream connection, and its cached response bytes are free.
```

## One hub owns each cache entry

Cache entries are local to a hub and survive a hub service restart there. They are not copied to
other hubs. Warming `hub-us-7.litport.net` does not warm `hub-eu-1.litport.net`, but the same Litport
root certificate works on both cache-enabled hubs.

```docs-figure
cache-hub-local
The same cache-enabled request is warm on hub-us-7.litport.net and cold on hub-eu-1.litport.net until that hub has its own entry.
```

## See what you saved

Traffic statistics can group usage by day, hour, or month. Every product shows free cached bytes;
pay-per-GB traffic also shows the dollar savings. Integrations can retrieve the same usage through
the [Account API](/docs/api/usage).

The cache suffix has no surcharge or multiplier. Misses and bypasses keep the normal price of the
selected proxy product or pool; only cached hit response bytes are free.

## What is eligible

**Password selects cache → HTTP proxy ingress → target is HTTPS → method is GET → path ends in a
selected static type → request has no private or partial-content signals → response is 200 and
cacheable.** A failed step becomes a normal billed proxy request; it does not fail solely because it
was not cacheable.

Supported groups:

- **Images:** PNG, JPEG, GIF, SVG, ICO, and WebP
- **Scripts:** JavaScript, CSS, WebAssembly, and source maps
- **Fonts:** WOFF, WOFF2, TTF, EOT, and OTF

The full URL is the cache identity, including the exact query string. Responses with cookies,
authorization, byte ranges, unsupported `Vary`, or request no-cache directives always bypass.

## Why HTTPS only?

```docs-figure
cache-https-only
HTTPS gives Litport an independently authenticated origin leg before a shared response is stored. Plain HTTP cannot provide that integrity guarantee.
```

Litport continues to proxy ordinary `http://` targets normally. They are not cached because an
unverified response could be altered between the hub and origin; storing it would turn one network
interception into shared cache poisoning. Installing the Litport CA or disabling certificate checks
does not make a plain-HTTP target eligible.

## Safe defaults

The default cache duration is 120 minutes, capped by the origin's `s-maxage` or `max-age` when that
is shorter. `_cacheignoreheader-1` can store a response even when the origin marks it `private`,
`no-cache`, or `no-store`; its requested duration starts when Litport stores the complete response.
Use that override **only for public, unauthenticated static assets**. Entries are shared among
Litport customers on the same hub, so ignoring origin privacy instructions for personalized content
is unsafe.

Continue with [certificate setup](/docs/proxy-cache/certificate), or open the
[complete cache reference](/docs/proxy-cache/reference).