# Constile proxy The Constile proxy runs the Constile gate in front of any self-hosted site. It's a small Node server in a Docker image, with no dependencies beyond Node 22. Your web server (nginx, Apache, or Caddy) keeps serving people as it does today. It sends the proxy only the requests the gate cares about. The proxy shows an AI agent that fetches a page for a person the Constile offer, and passes everything else to your site unchanged. ## Paywalled content Gate 0.6.0 and later can fetch a paywalled article with the release instructions the network sends, so an agent gets the full text and the offer fits it. The network gives the gate a page address on your site's own host and, optionally, headers to send: `Cookie`, `Authorization`, `Constile-Paywall-Key`, or a header starting with `X-`. The gate ignores an address on another host and drops other headers. It strips `Set-Cookie` from what it releases and never logs the headers. To set up a method, open your site's page in the dashboard and choose a content API, a paywall rule, or a Constile login. A paywalled page gets offers only after the method works and the gate is 0.6.0 or later. ## How it works ``` person ──> web server ──> your app agent ──> web server ──> Constile proxy ──> your app └──> Constile network ``` Your web server sends these requests to the proxy: - The gate's own paths: `/.well-known/constile`, and the `/sponsored/` paths the offer uses (`deferred`, `prepared`, `delivered`, `content`, and `offer`). Other pages under `/sponsored/` on your site stay with your site. - Requests with a `Signature` header. An agent that signs its requests (Web Bot Auth) may use an ordinary browser's user agent. - Requests whose user agent names a registered agent that fetches pages for people, such as `Claude-User` or `ChatGPT-User`. Search engines and crawlers go straight to your site. - If your site offers access to unknown clients, requests that don't look like they come from a browser. The proxy fetches the page from your app and decides what to send back: - An agent fetching an eligible page for a person gets the offer. - Everyone else gets your app's response, byte for byte, compression included. The proxy adds `Constile-Gate-Bypass: proxy` to every request it sends your app. The snippets send any request with that header to your app, so the proxy can fetch pages through your web server without looping back to itself. If one of its own requests comes back to it anyway (for example, `CONSTILE_ORIGIN` names the proxy), the proxy answers `508 Loop Detected` and logs a warning. The proxy fails open. If the network is slow or down, the proxy waits at most 5 seconds (`CONSTILE_NETWORK_TIMEOUT_MS`), then serves the page as if the gate weren't there. After it fails to fetch the site's settings, it doesn't ask the network again for 30 seconds, so pages don't keep waiting. ## Build the image To build the image from the copy the network serves, run: ```bash docker build -t constile-proxy https://NETWORK/install/constile-proxy-0.6.0.tar.gz ``` Replace `NETWORK` with the network's address. To build from a downloaded copy, pass the file on standard input: ```bash docker build -t constile-proxy - < constile-proxy-0.6.0.tar.gz ``` `docker build` doesn't accept a path to a local `.tar.gz` file as the build context. Use a URL or standard input. The image runs as the unprivileged `node` user and listens on port 8080. ## Settings The proxy reads its settings from environment variables. Your site page in the publisher dashboard shows your site ID, site secret, and network URL. | Variable | Required | What it does | | --- | --- | --- | | `CONSTILE_ORIGIN` | Yes | Your app's address, such as `http://app:3000`. The proxy sends requests here. No path. | | `CONSTILE_SITE_ID` | Yes | Your site ID. | | `CONSTILE_SITE_SECRET` | Yes | Your site secret. Keep it out of shell history and version control. | | `CONSTILE_NETWORK_URL` | Yes | The network's address. | | `CONSTILE_TRUSTED_PROXIES` | Usually | Addresses or CIDR ranges of your web server or load balancer, separated by commas, such as `10.0.0.0/8`. See [Trusted proxies](#trusted-proxies). | | `CONSTILE_NETWORK_TIMEOUT_MS` | No | How long a call to the network may take, in milliseconds. Default `5000`. | | `CONSTILE_ACCESS_LOG` | No | Set to `off` to stop the request log. | | `CONSTILE_DISABLED` | No | Set to `1` to turn the gate off: every request goes to your app unchanged, and nothing goes to the network. To apply it, create the container again (`docker rm -f constile`, then the same `docker run`, or `docker compose up -d`); `docker restart` keeps the old settings. | | `PORT` | No | The port the proxy listens on. Default `8080`. | If `CONSTILE_SITE_ID`, `CONSTILE_SITE_SECRET`, or `CONSTILE_NETWORK_URL` is missing, the proxy logs one warning and passes every request through. If `CONSTILE_ORIGIN` is missing or isn't an `http` or `https` address, the proxy doesn't start. ### Trusted proxies The gate sends the network the visitor's address, which the network uses to confirm that a request claiming to be a registered agent comes from that agent's operator. The proxy reads the address from the connection. Behind a web server, every connection comes from the web server, so the proxy needs to know which addresses it can believe `X-Forwarded-For` from. Set `CONSTILE_TRUSTED_PROXIES` to your web server's address, as the proxy sees it. For requests from those addresses, the proxy: - takes the visitor's address from `X-Forwarded-For`, reading from the right and stopping at the first address that isn't trusted, so a visitor can't forge it; - takes the site's public host name from `X-Forwarded-Host` and the scheme from `X-Forwarded-Proto`. When either header lists several values, the proxy takes the last one, which your web server added; a visitor's own value comes earlier in the list. From any other address, the proxy ignores those headers. If it sees them from an address you haven't trusted, it logs one warning that names the address. With Apache, `CONSTILE_TRUSTED_PROXIES` is required: Apache sends the proxy's own address as the `Host` header and your site's host name in `X-Forwarded-Host`. ### What your app receives The proxy forwards the method, path, query, headers, and body unchanged, and streams bodies in both directions. It also: - sends the visitor's `Host` header, as nginx does with `proxy_set_header Host $host`. For an `https` origin, it checks the certificate against that host name; - sets `X-Forwarded-For` (adding the address it received the request from), `X-Forwarded-Host`, and `X-Forwarded-Proto`; - removes hop-by-hop headers, such as `Connection` and `Keep-Alive`; - limits `Accept-Encoding` to `gzip` and `br`, so the gate can read the pages it shows agents; - adds `Constile-Gate-Bypass: proxy`. If your app trusts forwarded headers only from known proxies, add the proxy's address to that list. ## Run it with Docker To keep the site secret out of your shell history, put the settings in a file that only you can read: ```bash cat > constile.env <<'EOF' CONSTILE_ORIGIN=http://host.docker.internal:3000 CONSTILE_SITE_ID=site_... CONSTILE_SITE_SECRET=... CONSTILE_NETWORK_URL=https://NETWORK CONSTILE_TRUSTED_PROXIES=172.17.0.1 EOF chmod 600 constile.env ``` Then start the proxy, listening only on the server's loopback address: ```bash docker run -d --name constile --restart unless-stopped \ --env-file constile.env \ --add-host host.docker.internal:host-gateway \ -p 127.0.0.1:8080:8080 \ constile-proxy ``` In this example, your app listens on port 3000 on the same server, and your web server reaches the proxy at `http://127.0.0.1:8080`. With Docker's default network on Linux, the proxy sees your web server's requests come from the bridge gateway, usually `172.17.0.1`. If you're not sure, start without `CONSTILE_TRUSTED_PROXIES`, send a request through your web server, and read the warning in `docker logs constile`, which names the address. The `--add-host` line lets the container reach your app as `host.docker.internal`. Without it, Linux can't resolve that name, and every request through the proxy fails with `502 Bad Gateway`. The proxy logs why (see [Logs](#logs)), and `/healthz` reports `"origin_reachable": false`. `CONSTILE_ORIGIN` can be your app or your web server itself. If your web server serves the site directly (for example, PHP through Apache), point `CONSTILE_ORIGIN` at the web server: the snippets send the proxy's own requests to the site. ## Run it with Docker Compose Build the image first (see [Build the image](#build-the-image)). Then add the proxy next to your app and web server: ```yaml services: app: image: your-app constile: image: constile-proxy restart: unless-stopped env_file: constile.env # CONSTILE_SITE_ID, CONSTILE_SITE_SECRET, CONSTILE_NETWORK_URL environment: CONSTILE_ORIGIN: http://app:3000 CONSTILE_TRUSTED_PROXIES: 172.30.0.10 networks: default: { ipv4_address: 172.30.0.20 } web: image: nginx:1.30-alpine ports: ["80:80", "443:443"] volumes: ["./nginx.conf:/etc/nginx/nginx.conf:ro"] depends_on: [app, constile] networks: default: { ipv4_address: 172.30.0.10 } networks: default: ipam: config: - subnet: 172.30.0.0/24 ``` In the web server's snippet, set the proxy address to `http://constile:8080`. The fixed addresses let you trust exactly the web server. Don't publish the proxy's port: only your web server needs it. ## Run it in Kubernetes Run the proxy as a sidecar container in your app's pod. The proxy reaches your app on `127.0.0.1`. ```yaml containers: - name: app image: your-app ports: [{ containerPort: 3000 }] - name: constile image: registry.example.com/constile-proxy:0.6.0 ports: [{ containerPort: 8080, name: gate }] env: - { name: CONSTILE_ORIGIN, value: "http://127.0.0.1:3000" } - { name: CONSTILE_SITE_ID, value: "site_..." } - name: CONSTILE_SITE_SECRET valueFrom: { secretKeyRef: { name: constile, key: site-secret } } - { name: CONSTILE_NETWORK_URL, value: "https://NETWORK" } - { name: CONSTILE_TRUSTED_PROXIES, value: "10.0.0.0/8" } readinessProbe: { httpGet: { path: /healthz, port: 8080 } } livenessProbe: { httpGet: { path: /healthz, port: 8080 } } resources: { requests: { cpu: 50m, memory: 64Mi } } securityContext: { runAsNonRoot: true, allowPrivilegeEscalation: false, readOnlyRootFilesystem: true } ``` Keep in mind: - Push the image to a registry your cluster can pull from. - To send all of the site's traffic through the gate, point your Service's `targetPort` at `gate` (8080). The proxy then forwards people's requests too. It fetches the site's settings from the network at most once per cache period (10 seconds to an hour), not once per request. - To send only agent traffic to the gate, keep the Service on your app, add a second Service for port 8080, and put one of the snippets below in the web server in front. - Set `CONSTILE_TRUSTED_PROXIES` to the address range your ingress controller or load balancer connects from, such as your cluster's pod range. ## Web server snippets Your site page in the publisher dashboard shows these snippets with the network's current agent list. Copy them from there, so new agents reach the gate. The examples below show the agents as of version 0.5.0 that fetch pages for people and aren't blocked, with the proxy at `http://127.0.0.1:8080`. Each snippet also lets you: - give the proxy's address, if it isn't `http://127.0.0.1:8080`; - route unknown clients, if your site offers access to them; - rename its variables, if one web server serves several sites with different settings. After you add a snippet, check the install from your site page, or run: ```bash curl https://www.example.com/.well-known/constile curl -A "Claude-User/1.0" https://www.example.com/articles/an-eligible-page ``` The first answer names the platform `proxy`. The second shows the offer once your site is approved. ### nginx The snippet has two parts. The `map` blocks go in the `http` block, for example in a file in `/etc/nginx/conf.d/`. The rest goes in your site's `server` block. nginx runs a `server`-level `if` before it picks a location, so the snippet routes gate traffic whatever your `location` blocks do, and leaves them unchanged for everyone else. ```nginx # 1. In the http block: map $http_user_agent $constile_agent { default 0; "~*(?:chatgpt-agent|chatgpt-user|claude-agent|claude-user|duckassistbot|google-agent|meta-externalfetcher|mistralai-user|perplexity-user)" 1; } map $http_signature $constile_signed { "" $constile_agent; default 1; } map $uri $constile_route { "~^/sponsored/(?:deferred|prepared|delivered|content|offer)/" 1; "/.well-known/constile" 1; default $constile_signed; } # Requests from the proxy itself carry Constile-Gate-Bypass, and go to your site. map $http_constile_gate_bypass $constile { "" $constile_route; default 0; } # 2. In your site's server block, before its location blocks: error_page 418 = @constile; if ($constile) { return 418; } location @constile { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; } ``` To check the configuration before you reload, run `nginx -t`. ### Apache The snippet needs `mod_rewrite`, `mod_proxy`, `mod_proxy_http`, and `mod_headers`. On Debian and Ubuntu, enable them with `a2enmod rewrite proxy proxy_http headers`. Put the snippet in your site's `` (in each one, if you have separate HTTP and HTTPS hosts), before your other rewrite rules. ```apache RewriteEngine On # Requests from the proxy itself carry Constile-Gate-Bypass, and go to your site. RewriteCond %{HTTP:Constile-Gate-Bypass} ^$ RewriteCond %{REQUEST_URI} ^/sponsored/(?:deferred|prepared|delivered|content|offer)/ [OR] RewriteCond %{REQUEST_URI} ^/\.well-known/constile$ [OR] RewriteCond %{HTTP:Signature} . [OR] RewriteCond %{HTTP_USER_AGENT} (?:chatgpt-agent|chatgpt-user|claude-agent|claude-user|duckassistbot|google-agent|meta-externalfetcher|mistralai-user|perplexity-user) [NC] # The path as the visitor sent it, still encoded. Apache adds the query string itself. RewriteCond %{THE_REQUEST} ^\S+\s+(/[^?\s]*) RewriteRule ^ http://127.0.0.1:8080%1 [P,L,NE,E=constile_proto:%{REQUEST_SCHEME}] RequestHeader set X-Forwarded-Proto %{constile_proto}e env=constile_proto # mod_proxy adds your site's host name to X-Forwarded-Host; drop any the visitor sent. RequestHeader unset X-Forwarded-Host env=constile_proto ``` Apache sends the proxy your site's host name in `X-Forwarded-Host`, so set `CONSTILE_TRUSTED_PROXIES` to the address the proxy sees Apache's requests come from. The rule passes the path on exactly as the visitor sent it, from the request line, so encoded characters such as `%3F` and `%2B` reach the gate unchanged. To check the configuration before you reload, run `apachectl configtest`. ### Caddy Put the snippet in your site block. ```caddy # Requests from the proxy itself carry Constile-Gate-Bypass, and go to your site. @constile `!header({'Constile-Gate-Bypass': '*'}) && ( path_regexp(r'^/sponsored/(?:deferred|prepared|delivered|content|offer)/') || path('/.well-known/constile') || header({'Signature': '*'}) || header_regexp('User-Agent', r'(?i)(?:chatgpt-agent|chatgpt-user|claude-agent|claude-user|duckassistbot|google-agent|meta-externalfetcher|mistralai-user|perplexity-user)') )` handle @constile { reverse_proxy http://127.0.0.1:8080 } ``` Caddy runs `handle` blocks that match a single path, such as `handle /blog/*`, before this one. If your site block has those, wrap the snippet and your `handle` blocks in one `route` block, with the snippet first. Caddy keeps the blocks inside `route` in the order you write them. To check the configuration before you reload, run `caddy validate --config /etc/caddy/Caddyfile`. ## Caches and CDNs The offer page carries `Cache-Control: no-store` and `Vary: User-Agent`, so a cache that follows those headers doesn't keep it. Don't configure a cache in front of the proxy to ignore `Cache-Control`. If a CDN serves your pages from its cache, an agent's request may never reach your web server; exclude the agent user agents from the CDN's cache, or bypass the cache for them. ## Logs The proxy writes one line per request to standard output: the time, method, path (without the query string), status, and duration. ``` 2026-11-17T16:36:02.193Z GET /articles/espresso-grinders 200 41ms ``` Warnings go to standard error: missing settings, forwarded headers from an untrusted address, a request that looped back to the proxy, and errors reaching your app. The proxy logs each new error reaching your app once, such as `getaddrinfo ENOTFOUND host.docker.internal`, and logs again when your app is reachable. The proxy never logs the site secret. ## Health check `GET /healthz` answers `200` with: ```json {"ok":true,"version":"constile-gate 0.6.0","configured":true,"origin_reachable":true} ``` - `configured` is `false` when the proxy is passing everything through because a setting is missing. - `origin_reachable` says whether the proxy's last request to your app got an answer: `true`, `false`, or `null` before the first request. The log has the error. `/healthz` stays `200` when your app is down, so a restart policy doesn't restart the proxy for your app's outage. The image's `HEALTHCHECK` uses it. The proxy answers `/healthz` itself, so an agent routed to the proxy can't reach a `/healthz` page on your app. ## Limits - The proxy doesn't forward WebSocket upgrades. Send them straight to your app. With the snippets, they don't reach the proxy unless an agent sends them. - The proxy reads pages compressed with gzip or Brotli. If your app sends a page compressed another way, the proxy passes it through without an offer. ## Develop From the repository root, run `npm install` once. Then, in `integrations/proxy`: | Command | What it does | | --- | --- | | `npm test` | Type-checks, builds `dist/`, and runs the unit tests (`node:test`). | | `npm run test:compose` | Runs nginx, Apache, and Caddy in Docker Compose, each in front of a demo app with its generated snippet, and checks what reaches the proxy. Needs Docker and `openssl`. | | `./build.sh [outdir]` | Writes `constile-proxy-0.6.0.tar.gz`, the Docker build context, to `outdir` (default `apps/network/public/install/`). | The server is `src/server.ts`, bundled with esbuild from the shared gate in `packages/gate`. The snippet generator is `src/snippets.ts`; it exports `snippet(server, agents, options)` for the dashboard.