Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Subpath & Reverse Proxy Setup

By default, custom short links in Shaf use dedicated apex domains or subdomains (such as link.acme.com/:slug). However, many organizations prefer hosting short links directly under a subdirectory of their primary brand website—such as acme.com/go/:slug or company.org/link/:slug.
Using Subpath Reverse Proxying, your existing web server or CDN handles your main website as normal, while seamlessly delegating link requests under a designated prefix (e.g. /go/*) to Shaf's global edge network.

When to Use Subdirectory Proxying

FeatureDedicated Domain / Subdomain (link.acme.com)Subpath Reverse Proxy (acme.com/go)
Domain RequirementRequires a dedicated subdomain or root domainUses your existing primary website domain
DNS ConfigurationRequires creating a CNAME record at your DNS providerZero DNS changes required
Brand PresenceHosted on secondary hostRetains 100% brand equity on primary domain
InfrastructureDirectly points to Shaf edgeReverse proxy forwards subpath traffic to Shaf
AuthenticationDNS ownership verificationCryptographic secret header (X-Shaf-Proxy-Secret)

Request Architecture

Rendering diagram...

Step 1: Register Subdirectory in Shaf Console

  1. Navigate to Domains in your Shaf workspace dashboard.
  2. Click Add Domain.
  3. Under Routing Mode, select Subdirectory / Reverse Proxy.
  4. Enter your main website hostname in Primary Hostname (e.g. acme.com).
  5. Enter your desired prefix in Subpath Prefix (e.g. /go or /links).
  6. Click Add Custom Domain.
Save your Proxy Secret Token: Upon registration, Shaf generates a unique Proxy Secret Token (e.g. spt_live_9a7f2c8d1e4b). You must include this token in your reverse proxy configuration to authenticate forwarded requests.

Step 2: Configure Your Reverse Proxy

Select your web server, CDN, or hosting platform below for ready-to-use configuration recipes:
Add the following location block inside your existing HTTPS server block:
location /go/ {
    # 1. Forward request to Shaf's edge gateway
    proxy_pass https://cname.shaf.app;

    # 2. Host & tenant headers
    proxy_set_header Host cname.shaf.app;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 3. Authentication secret (from your Shaf dashboard)
    proxy_set_header X-Shaf-Proxy-Secret "spt_live_YOUR_SECRET_TOKEN";

    # 4. Mandatory TLS & SNI handshake directives
    proxy_ssl_name cname.shaf.app;
    proxy_ssl_server_name on;
    proxy_ssl_protocols TLSv1.2 TLSv1.3;

    # 5. Performance and buffering
    proxy_buffering off;
    proxy_connect_timeout 5s;
    proxy_read_timeout 10s;
}
Mandatory SNI Directives: You must include proxy_ssl_name cname.shaf.app; and proxy_ssl_server_name on;. If omitted, Nginx sends your domain (acme.com) in the TLS SNI handshake to Cloudflare edge, triggering an immediate SSL_ERROR_UNRECOGNIZED_NAME_ALERT connection failure.

Step 3: Verify the Connection & Probe

Shaf includes an automated health probe endpoint (/__shaf_probe) at every configured subpath.

1. Test via Command Line

Run curl from your terminal against your proxy URL:
curl -i https://acme.com/go/__shaf_probe
Expected Response (200 OK):
HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: no-store

{"status":"ok","probe":"shaf_verified"}
If you receive this response, your proxy is correctly terminating TLS, passing headers, and reaching Shaf's edge!

2. Activate in Dashboard

  1. Return to Domains in your Shaf Dashboard.
  2. Locate your subpath domain (status: Pending).
  3. Click Verify Proxy Probe.
  4. Shaf executes an automated HTTPS request to https://acme.com/go/__shaf_probe. Once verified, the domain badge turns Active.

Step 4: Subpath Root Redirection

What happens if a visitor navigates directly to https://acme.com/go without specifying a link slug?
By default, Shaf redirects bare subpath root visits to your primary website (https://acme.com). You can customize this target:
  1. Click Configure on your active subpath domain.
  2. In Root Redirect URL, enter a custom destination (e.g. https://acme.com/deals or https://acme.com/campaigns).
  3. Click Save Settings.

Troubleshooting Guide

SymptomCauseSolution
SSL_ERROR_UNRECOGNIZED_NAME_ALERTYour proxy sends your domain in the SNI handshake instead of cname.shaf.app.Ensure proxy_ssl_name cname.shaf.app; and proxy_ssl_server_name on; (Nginx) or tls_server_name cname.shaf.app (Caddy) are configured.
401 UnauthorizedMissing or mismatched X-Shaf-Proxy-Secret header.Verify the token in your proxy matches the Proxy Secret Token shown in the Shaf dashboard.
404 Not Found (on existing links)Path prefix was not stripped or was double-prefixed.Shaf accepts both intact paths (/go/:slug) and stripped paths (/:slug). Ensure your proxy forwards the URI correctly.
Visitor analytics show proxy IP instead of real visitorMissing X-Forwarded-For header.Configure proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; in your proxy.
Probe test fails with Probe cannot target private networkDomain resolves to localhost or private RFC 1918 IP address.Shaf's probe engine blocks loopback and private IPs to prevent SSRF vulnerabilities. Ensure your domain resolves to a publicly routable IP address.