---
title: "HitKeep Trusted Proxy Configuration Guide | HitKeep"
description: "Configure trusted reverse proxy CIDRs in HitKeep so real client IP addresses are used for IP metadata, rate limiting, spam checks, and exclusions."
canonical: "https://hitkeep.com/guides/installation/trusted-proxies/"
---

# HitKeep Trusted Proxy Configuration Guide

HitKeep runs behind a reverse proxy in virtually every production setup. If HitKeep cannot trust the proxy chain, every request appears to come from the proxy’s IP address, which breaks derived IP metadata accuracy, rate limiting, spam checks, and IP exclusions.

## The Problem

When Caddy, Traefik, nginx, a load balancer, or CloudFront sits in front of HitKeep, the real visitor’s IP is passed in a forwarded header (`X-Forwarded-For`, `X-Real-IP`, or CDN-specific headers). If HitKeep does not trust the direct peer, it ignores these headers and uses the direct connection IP: your proxy’s IP.

**Without trusted proxies configured:**

- All visitors appear to come from `127.0.0.1` or your proxy’s private IP.
- Country, region, city, provider, and ASN metadata is wrong or unknown.
- IP exclusion rules match the proxy IP, not the visitor’s IP.
- Rate limiting applies to the proxy IP, not individual visitors.

## Configuration

Set the `--trusted-proxies` flag (or `HITKEEP_TRUSTED_PROXIES` env var) to a comma-separated list of CIDRs that represent your reverse proxy or load balancer:

```
hitkeep --trusted-proxies="127.0.0.1/32,10.0.0.0/8"
```

Or via environment variable:

```
HITKEEP_TRUSTED_PROXIES=127.0.0.1/32,10.0.0.0/8
```

Once a direct connection IP matches a trusted CIDR, HitKeep reads the real client IP from `X-Forwarded-For`. HitKeep uses that resolved IP transiently to derive country, region, city, provider, and ASN metadata, then stores the derived fields on hits. It does not store the raw visitor IP.

The default value is `*`, which trusts forwarded client IP headers from any direct peer. This is convenient for managed and simple proxy setups. For self-hosted production instances, set explicit CIDRs for the reverse proxies or load balancers you control.

## Common Configurations

### Local Reverse Proxy (same host)

Caddy or nginx running on the same machine:

```
HITKEEP_TRUSTED_PROXIES=127.0.0.1/32
```

If Caddy also serves the site you want to track, the community [Caddy HitKeep plugin](https://hitkeep.com/guides/tracking/server-side-tracking/#caddy-reverse-proxy-option) can forward pageviews from Caddy to HitKeep’s authenticated server-side pageview endpoint. This is separate from configuring trusted proxies for HitKeep itself: keep the HitKeep API token in Caddy’s server-side configuration, and set `HITKEEP_TRUSTED_PROXIES` for the proxy chain that sends requests to HitKeep.

### Docker Compose

Both services in the same Docker network (e.g., `172.16.0.0/12`):

```
HITKEEP_TRUSTED_PROXIES=172.16.0.0/12
```

### Kubernetes

Traffic arriving from the cluster’s pod CIDR:

```
HITKEEP_TRUSTED_PROXIES=10.0.0.0/8
```

### Cloud Load Balancer

If using an external load balancer, add its egress CIDR. Consult your cloud provider’s documentation for the specific ranges.

## Verification

After configuring trusted proxies, use the current-IP endpoint to confirm HitKeep is seeing your real IP:

```
curl https://your-hitkeep.example/api/user/current-ip \
  -b "hk_token=YOUR_SESSION_COOKIE"
```

The response should return your actual public IP, not the proxy’s IP. If it still returns the proxy IP, double-check that the CIDR covers the proxy’s address and that the proxy is setting `X-Forwarded-For`.

## Security Note

Only add IP ranges you fully control to the trusted list. A misconfigured or overly broad CIDR allows a client to spoof their IP by setting a `X-Forwarded-For` header, which undermines rate limiting and IP exclusion rules.

## Configuration Reference

| Flag | Env Variable | Default | Description |
| --- | --- | --- | --- |
| -trusted-proxies | HITKEEP_TRUSTED_PROXIES | * | Comma-separated list of trusted proxy CIDRs (e.g. 10.0.0.0/8,127.0.0.1/32) or * to trust forwarded client IP headers from any direct peer. |

Full reference: [Configuration Reference](https://hitkeep.com/reference/configuration/#trusted-proxies).

## Related

- [IP Exclusions](https://hitkeep.com/guides/tracking/ip-exclusions/)
- [Server-Side Tracking](https://hitkeep.com/guides/tracking/server-side-tracking/)
- [Configuration Reference](https://hitkeep.com/reference/configuration/)
- [Docker Compose Installation](https://hitkeep.com/guides/installation/docker-compose/)
- [Kubernetes and Helm Installation](https://hitkeep.com/guides/installation/kubernetes/)

[Previous Kubernetes and Helm](https://hitkeep.com/guides/installation/kubernetes/)[Next Performance and memory](https://hitkeep.com/guides/installation/performance/)