> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slipway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Edge caching

> Cache responses at the edge, close to your users.

Edge caching serves repeat responses from slipway's global edge network without the
request ever reaching your container. Cached pages and assets load faster everywhere
in the world, and your service does less work — a cache hit costs it nothing at all.

Caching is set per service and applies to the service's **platform URL**
(`<service>.<apps domain>`). It is available on paid plans (see [Plans](/plans)).

## Modes

| Mode | What is cached |
| - | - |
| **Off** (default) | Nothing. |
| **Static files only** | Only asset-shaped paths — stylesheets, scripts, images, fonts, archives and similar. |
| **All files** | Every cacheable response, whatever the path. |

In both active modes only `GET` and `HEAD` requests are served from cache, and a
response is cached only when it is safe to share:

* Responses with a `Set-Cookie` header are **never** cached.
* Requests carrying an `Authorization` header always bypass the cache.
* `Cache-Control: no-store`, `no-cache` and `private` disable caching for that response.

## Controlling freshness

The cache honors your response headers, so the finest-grained control is per route,
in your app:

* `Cache-Control: max-age=<seconds>` sets how long a response is served from cache.
* `s-maxage` overrides `max-age` for the shared cache, without affecting browsers.
* `CDN-Cache-Control` overrides `Cache-Control` entirely at the edge when both are set.

When a cacheable response carries no explicit freshness, defaults by status code apply:

| Status | Default TTL |
| - | - |
| `200`, `301` | 120 minutes |
| `302`, `303` | 20 minutes |
| `404`, `410` | 3 minutes |

Other status codes are not cached unless the response says so explicitly.

## Purging

The cache is **purged automatically on every deploy** — a new deployment never serves
the previous build's responses. To purge on demand, open the service's **Networking**
tab and press **Purge cache**; the purge reaches every edge location within about two
minutes. Rollbacks purge too, since a rollback is a new deploy.

## Turning it on

**Console**

Open the service, then **Networking**, and pick a mode under **Edge caching**.
Changes apply live — no redeploy — and reach the edge within about two minutes.

**slipway.yaml**

Set `edgeCache:` on the service:

```yaml slipway.yaml theme={"system"}
version: 1

services:
  - name: web
    rootDir: .
    ports:
      - port: 3000
        public: true
    edgeCache: static   # off | static | all
```

The service's **Networking** tab overrides the field for that project. Once you
change it in the console, the console value wins on every deploy.

Every response on a cached service carries an `x-slipway-cache` header: `HIT` (served
from cache), `MISS` (fetched from your service and possibly stored), or `BYPASS` (a
request shape the cache never answers).

## Interaction with other features

* **Sleep**: cache hits keep serving while the service sleeps, and count as activity —
  a service under cached traffic is not put to sleep. A miss wakes it as usual.
* **[Inbound IP rules](/networking/inbound-ip-rules)**: enforced at the edge before the
  cache — a blocked IP never gets a cached response.
* **[Access control](/networking/access-control)**: caching and a sign-in wall don't
  compose (a cached response would be served past the wall), so a service with access
  control on can't enable caching, and vice versa.
* **Custom domains** bypass the edge cache — caching applies to the platform URL only.
* **Static sites** are always served from the edge cache by construction and don't
  carry the setting.
* **PR previews** are never cached.

## Limitations

* The `Vary` header is not supported beyond `Accept-Encoding`; responses that vary on
  anything else are not cached.
* `Range` requests (partial content) always bypass the cache.
* Concurrent misses for the same URL each reach your service — requests are not
  coalesced while a response is being fetched.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.