Help & Documentation

Installation

Sidien ships as a single executable inside a .zip - no Python, no dependencies, no installer wizard. Download it, extract it, write a small .env config file next to it, and run it.

Windows

1. Download sidien-windows.zip from sidien.net/downloads
2. Extract it into a folder (e.g. C:\Sidien\) - you'll get sidien-windows.exe
3. In the same folder, create a file named .env with at least:

   PROJECT_NAME=mysite
   ORIGIN_URL=https://your-real-origin.example.com
   ADMIN_TOKEN=choose-a-long-random-token
   ADMIN_PATH=/admin-something-private
   PORT=8080

4. Double-click sidien-windows.exe (or run it from a terminal to see logs). To keep it running in the background long-term, set it up as a Windows Service using a tool like NSSM.
5. Point your domain's DNS (or your existing reverse proxy/load balancer) at this server's IP and port.

Linux

1. Download the archive: curl -O https://sidien.net/downloads/sidien-linux.zip
2. Extract it: unzip sidien-linux.zip - you'll get a sidien-linux binary
3. Make it executable: chmod +x sidien-linux
4. Create a .env file next to it (same content as the Windows example above)
5. Run it directly to test: ./sidien-linux - or set it up as a systemd service for production so it restarts automatically and survives reboots.
6. Point your domain's DNS at this server's IP and port.

Nginx + Cloudflare Setup

The most common production setup is: Cloudflare → Nginx → Sidien → Origin. Here is the correct Nginx config and the mistakes to avoid.

Correct Nginx config

map $http_upgrade $connection_upgrade {
    default keep-alive;
    websocket upgrade;
}

server {
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto https;

        # WebSocket support — only upgrade when the client actually requests it
        proxy_set_header   Upgrade    $http_upgrade;
        proxy_set_header   Connection $connection_upgrade;

        proxy_read_timeout 60s;
    }
}

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}

Cloudflare SSL/TLS mode

Set Cloudflare SSL/TLS to Full (not Flexible, not Full Strict):

• Flexible — Cloudflare connects to Nginx over plain HTTP. Nginx expects HTTPS → 502. Also causes redirect loops if your origin forces HTTPS.
• Full ✅ — Cloudflare connects to Nginx over HTTPS, accepts Let's Encrypt or self-signed certificates. This is what you want.
• Full (Strict) — Same as Full but requires a valid CA-signed cert. Works fine with Let's Encrypt.

Cloudflare port support

Cloudflare only proxies a limited set of ports. If Sidien is running on an unsupported port (e.g. 8081), Cloudflare will refuse to connect. Supported HTTP ports include: 80, 8080, 8880, 2052, 2082, 2086, 2095. Supported HTTPS ports: 443, 2053, 2083, 2087, 2096, 8443.

The simplest solution is to put Nginx in front of Sidien on port 443, as shown above — Sidien itself can run on any port.

Diagnosing 502s

If you get 502 errors only via the domain (not via curl http://127.0.0.1:PORT/), work through this checklist:

1. Check /var/log/nginx/error.log — connect() failed (111) means Nginx cannot reach Sidien's port. Check ss -tlnp | grep PORT to confirm Sidien is actually listening.
2. Test with the same headers Cloudflare/Nginx sends: curl -H "Host: yourdomain.com" -H "X-Forwarded-Proto: https" http://127.0.0.1:PORT/test — if this returns 200 but the domain returns 502, the issue is in Nginx, not Sidien.
3. Check Sidien's access.log (in the same folder as the binary). If origin=- appears, the request is hitting an early-exit code path before Sidien even tries the origin — usually a middleware block (IP rule, WAF, license check) or a WebSocket misdetection (see above).
4. If Sidien's log shows no entries at all when you hit the domain, requests are not reaching Sidien — the problem is between Cloudflare and Nginx.

Once it's running, open http://your-server:PORT/{ADMIN_PATH} (the path you chose above) in a browser and log in with your ADMIN_TOKEN to configure everything else.

Overview

Sidien is a self-hosted reverse proxy / CDN. It sits between your visitors and your real website (the origin), and can cache pages, rewrite content, block unwanted traffic, redirect requests, and more - all configured from this admin panel, with no code changes or redeploys needed for most changes.

What gets logged and what doesn't

Most security and monitoring features (Logs, Rate Limiting, IP/User-Agent rules, Page View analytics) only apply to real visitor traffic - your site's pages and the /__api__/ proxy. They deliberately exclude the admin panel itself and its management API calls, so you can never accidentally lock yourself out or pollute your analytics with your own admin panel usage.

Dashboard

The landing page when you log in. Shows at a glance:

• App Version and Server IP (the IP this server's license is tied to - see Licensing)
• License Status - if invalid, a red banner appears at the top of every page until it's fixed
• Tracked Clients - visitors currently being served from cache because your origin was unreachable for them (see Client Tracking)
• Page Views and Unique Visitors - counts only real HTML page loads (CSS, JS, images, and API calls are never counted). Use Reset Analytics to zero these out.

Regex Rules

Find-and-replace rules applied to every page's HTML before it's served. Useful for swapping out text, fixing broken links, or rewriting URLs site-wide.

• Each rule has a Pattern (a regular expression) and a Replacement string.
• Rules apply to the raw HTML text, in the order they're listed.
• Use Enable/Disable to temporarily turn a rule off without deleting it.

API Domains

If your site calls out to a separate API domain (e.g. api.example.com) directly from the browser, you can register that domain here so Sidien automatically rewrites those calls to go through its own /__api__/ proxy instead - useful for routing API traffic through the same caching/security layer, or for avoiding CORS/mixed-content issues.

Head Injection

Insert scripts, stylesheets, fonts, or any other HTML into the <head> of every page - typically used for analytics tags (Google Analytics, etc.) or site-wide custom CSS.

• Each snippet has a Name (for your own reference) and raw Content (the actual HTML to insert).
• All enabled snippets are inserted right before </head>, in order.

Element Injection

A more targeted version of Head Injection: find a specific point anywhere in the page (not just the <head>) using a regular expression, then insert your own HTML immediately before or after it.

Fields

Example

To insert a banner right after every page's first <h1>, only on pages whose URL contains /blog:

Applies to:        URL contains: /blog
Anchor (regex):    <h1>.*?</h1>
Position:          After
HTML to inject:    <div class="banner">Special offer!</div>

Redirects

Page Redirects

If an incoming request's path and query string match a rule, Sidien immediately redirects the visitor - without ever contacting your origin. This is fast, and works even for URLs that don't exist on your real site at all (much friendlier than a 404).

Choose a status code: 301 (permanent), 302 (temporary), 307/308 (strict - method and body are preserved by browsers).

Location Passthrough

Normally, if your origin server itself returns a redirect (a 3xx status with a Location header - e.g. after a login or checkout), Sidien follows it internally and serves the final page under the original proxied URL. That's usually what you want, but sometimes it's not - for example, a checkout flow that needs to send the visitor's actual browser to a separate payment domain. For paths matching a Location Passthrough rule, the origin's redirect is instead passed straight through to the visitor's browser, exactly as the origin sent it.

Cache Manager

Sidien caches your pages so repeat visits don't need to hit your origin server every time.

Cache Priority modes (Settings page)

Clear Cache by URL

Enter a full URL or just a path. All cached variants for that path - any query string, both GET and HEAD - are removed immediately. Use this right after editing a Regex Rule, Head Injection snippet, or Element Injection rule if you want to see the change without waiting for the cache to expire naturally.

Clear All

Wipes the entire cache. There's a short cooldown after clicking it to prevent accidental repeated full wipes (which would temporarily increase load on your origin as everything refetches).

Sidien-Cache header

Every response includes a Sidien-Cache header: HIT means it was served from cache, PASS means it came fresh from your origin. Handy when debugging with browser dev tools or curl -i.

Origin Proxy Pool

If your origin should be reached through a pool of upstream HTTPS proxies (e.g. to rotate IPs), add them here and toggle the pool on. When enabled, Sidien picks a random working proxy from the pool for each origin request instead of connecting directly.

URL Blacklist

Block specific URL patterns from ever reaching your origin. Matching requests get an immediate 204 No Content response. Useful for blocking known attack paths, old removed endpoints, or anything you simply don't want served.

IP Rules

An allow/deny list for IP addresses, applied only to real proxy traffic (never the admin panel - you can't lock yourself out).

• Deny list: any IP here is always blocked (403), even if it's also on the allow list.
• Allow list: if this list has any entries, it becomes exclusive - only those IPs may access the proxy, and everyone else is blocked. If the allow list is empty, everyone is allowed except IPs on the deny list.

User Agent Rules

A deny-only list (there's no allow list for User-Agents) matched against the User-Agent request header using a case-insensitive substring match. Useful for blocking known scraper tools or bots - e.g. adding curl blocks any request whose User-Agent contains the word "curl".

On-Demand Rules

An access-control mode independent of System Active. When turned on (from Settings), visitors need a valid "unlock" cookie to use the proxy normally.

How it works

1. A visitor's first request is checked against your On-Demand Rules - not their cookie (they don't have one yet).
2. Each rule has one or more conditions (does the query string or referrer contain/not-contain/equal/not-equal a value?) combined with ALL (AND) or ANY (OR) logic.
3. If a rule matches, that request is served normally and the visitor's browser receives a signed, tamper-proof cookie valid for the number of days you set on that rule.
4. Every later request only checks the cookie's signature and expiry - the rules are never re-evaluated for that visitor again until the cookie expires.
5. If there's no valid cookie and no rule matches, the fallback behavior applies (see below).

Fallback (Settings page)

When On-Demand Active is on and a request has neither a valid cookie nor a matching rule, choose what happens:

• Return 404 - simplest option, the proxy behaves as if the page doesn't exist.
• Proxy to a different origin - point unlocked-out visitors to an entirely different site (e.g. a "coming soon" page or a public preview) instead of your real origin.

Example

To grant 7-day access to anyone who clicks a special campaign link, while blocking referrals from a blocked competitor site:

Match:              ALL (AND)
Condition 1:        Query String contains "campaign=summer2026"
Condition 2:        Referrer does NOT contain "blocked-site.com"
Cookie duration:    7 days

Client Tracking

If your origin becomes unreachable or times out for a specific visitor, that visitor is tracked here. While tracked, they're served from cache (if available) instead of waiting on a slow/dead origin every time. Once the origin responds successfully again for that visitor, they're automatically removed from this list.

Data Capture

Define rules to capture specific fields from matching requests (e.g. form submissions, search queries) into a simple key/value store you can review later from this page. Useful for lightweight analytics or debugging without needing a separate analytics platform.

Logs

A record of real proxy traffic - method, path, status code, cache HIT/PASS, client IP, and response time. Admin panel usage and management API calls are deliberately excluded so this list stays focused on actual visitor traffic.

• Filter by method, status code, cache status, or search by path.
• New entries can take a few seconds to appear - they're written in small batches for performance rather than one at a time.
• Clear All Logs wipes the log history (this cannot be undone).

Logs are also automatically pruned after a configurable retention period so the database doesn't grow forever.

Page Rules

Evaluate conditions on every incoming request and take an action — block, allow, redirect, or return a custom response. Unlike On-Demand Rules, Page Rules run on every request and require no cookie. The first matching enabled rule wins.

Actions:

• Deny — return a configurable HTTP error (403, 404, 410, etc.)
• Allow — explicitly whitelist a path (useful when a catch-all deny is below)
• Redirect — 301 or 302 redirect to another URL
• Custom Response — return any status code, content-type and body (JSON, HTML, plain text, etc.)

Conditions can match on: Query String, URI (path + query), Hostname, Referrer, IP Address, Country Code, User-Agent, any Header, or any Cookie.

Maintenance Mode

Turns the proxy offline with a single click — visitors see a custom HTML page instead of your site. A configurable IP allow-list lets you (and only you) still reach the real site while it's in maintenance.

Maintenance Mode works by turning System Active off while showing a custom page instead of a plain 503. The admin panel always stays accessible so you can bring it back up.

Hotlink Protection

Prevents other websites from embedding your images, videos and downloadable files by inspecting the Referer header. Requests for protected file types (jpg, png, gif, webp, svg, mp4, mp3, pdf, zip) that originate from an unlisted domain get a 403 response.

Your own origin domain is always implicitly allowed. Add additional domains (e.g. a CDN or partner site) to the allowed list.

Basic Auth

Protects specific URL path prefixes with a native browser username/password dialog (HTTP 401 + WWW-Authenticate). Useful for staging environments, admin areas, or any path you want to restrict without building a login page.

You can create multiple rules for different prefixes (e.g. /staging with one password, /api-docs with another). Passwords are stored as SHA-256 hashes — never in plain text.

WAF — Web Application Firewall

Inspects every inbound request against a set of rules before it reaches your origin. Matching requests are blocked with a 403 response. The WAF has two rule sets:

• Built-in rules — 10 pre-written rules covering SQL injection (3), XSS (3), path traversal (2), command injection, and Shellshock. Each can be toggled individually.
• Custom rules — Write your own regex patterns. Choose what to inspect: the full URL path, the query string, or both combined. Useful for blocking specific bots, scrapers, or attack patterns specific to your site.

The WAF master switch must be enabled for any rules to apply. Individual rules can be enabled/disabled independently without touching the master switch.

Health Check & Uptime

Periodically pings your origin and records whether it responded successfully. Visible in the Origins panel.

• Check interval — how often to ping (seconds). Default 60s.
• Uptime % — calculated over the last 50 checks.
• Failover — if N consecutive checks fail, Sidien automatically switches to the next available origin in your Origins list. Switches back when the primary recovers.

The health check panel auto-refreshes every 30 seconds. You can also trigger a manual check immediately.

A/B Testing & Traffic Split

Routes a percentage of visitors to different origin servers. Useful for canary deployments, design experiments, or gradual rollouts.

Setup

1. Add at least two origins in the Origins panel.
2. Open A/B Testing and click Add Split for each origin.
3. Enter a percentage for each split — they must add up to 100%.
4. Enable the toggle and save.

Sticky sessions

When enabled, the same visitor always reaches the same origin (tracked via a cookie). Without sticky sessions, each request is independently routed based on the percentages — a visitor could see different origins on consecutive page loads.

Per-Path Cache TTL

Override the global cache TTL for specific URL path prefixes. The longest matching prefix wins.

Common patterns

• /api/ → TTL 0 (never cache — always fresh from origin)
• /assets/ → TTL 604800 (7 days — static files never change)
• /user/ → TTL 0 (personalised pages, must not be shared)
• /blog/ → TTL 3600 (1 hour — updated occasionally)

Setting TTL to 0 disables caching entirely for that prefix — every request goes to the origin. Rules are matched in order of longest prefix first, so /api/public/ beats /api/.

Backup & Restore

Export all rules and settings to a JSON file, and import them back on any Sidien instance.

Export

Click Download Backup JSON. The file contains all regex rules, redirects, IP rules, header rules, page rules, basic auth rules, path rate limits, origins, and settings.

Import

Two modes:

• Overwrite — deletes all existing rules first, then imports the backup. Use when migrating to a new server.
• Merge — adds the imported rules on top of existing ones. Use when copying rules from one project to another. Duplicate entries may appear.

SSL Certificate

Manages TLS termination when Sidien is running in direct HTTPS mode (without a reverse proxy like Nginx in front of it).

Self-signed certificate

Enter your domain and click Generate Certificate. This creates a self-signed cert valid for 365 days. Browsers will show a "Not Secure" warning — use only for development or internal tools, not for public sites.

Upload your own certificate

Upload a cert.pem and key.pem in PEM format (e.g. from Let's Encrypt via Certbot). After uploading, restart Sidien for the certificate to take effect.

Log Export

Download the request log as a CSV or JSON file from the Logs page.

• Click Export in the Logs panel header to reveal the export controls.
• Optionally set a From and To date to limit the export.
• Choose CSV (Excel-compatible) or JSON.
• Active filters (status code, path search) are applied to the export too.

Exports are limited to 50,000 rows. For larger datasets, query the SQLite database directly (the rules DB file sits next to the binary).

Licensing

Sidien runs with no license at all as a free tier - core caching, redirects, user-agent & URL blocking, and rate limiting all work without a key. Advanced features require a paid license and show a "Pro feature" lock screen until one is added.

There are three paid license types:

• Domain — tied to one domain (+ all subdomains). Set LICENSE_SERIAL in your .env and configure PROXY_DOMAIN in Settings to match the domain Sidien serves.
• Subscription — not tied to any IP or domain. Fully portable, valid until the subscription period expires.
• Lifetime — tied to a specific server's public IP address, never expires. Sidien detects this automatically.

How license validation works

Sidien validates your license against the Sidien license server over HTTPS at startup and every 24 hours. This is an online check — an internet connection is required.

If the license server is temporarily unreachable (network outage, maintenance), Sidien uses a locally cached validation result for up to 48 hours. After that, if the server is still unreachable, Pro features lock until connectivity is restored. This grace period is stored in an HMAC-signed local file to prevent tampering.

Proxy Domain setting

For Domain licenses, Sidien needs to know which domain it is serving traffic for. Set PROXY_DOMAIN=yourdomain.com in your .env (this is the domain visitors use to reach Sidien — not the origin/backend domain). You can also set this from Settings → License Information → Proxy Domain without a restart.

Re-checking the license

Go to Settings → License Information and click Re-check now to force an immediate fresh validation, bypassing the 30-minute in-memory cache. Useful after purchasing a license or after a revocation/un-revocation.

Scans incoming requests for common attack patterns and blocks them before they reach your origin. Each rule can be toggled individually. Rule targets:

• path — URL path only
• query — query string only
• all — path + query string combined

Included rule categories: SQL Injection (3 rules), XSS (3 rules), Path Traversal (2 rules), Command Injection, Shellshock. Matching requests get an immediate 403.

Header Rules

Add, overwrite, or remove HTTP headers on requests going to your origin (Request) and/or responses going back to the browser (Response). Common uses:

• Security headers: Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options
• CORS headers: Access-Control-Allow-Origin
• Remove fingerprinting headers: Server, X-Powered-By
• Inject auth tokens into origin requests

Quick Presets cover the most common security headers with a single click.

Origins

Manage multiple backend origins from the panel instead of editing .env. The Primary origin receives all proxy traffic. Switching primary:

• Takes effect immediately — no restart needed
• Automatically clears the cache — content from the old origin won't be served to new visitors
• Closes and re-creates the HTTP connection pool — prevents stale connections to the old origin

If you haven't added any origins through the panel, the proxy uses ORIGIN_URL from your .env file as before.

Auto-Minify

Compresses HTML, CSS and JavaScript responses before writing them to cache. Applied once on the first request — subsequent responses are served from cache already minified, so there's no per-request overhead.

HTML minification removes comments and collapses whitespace. CSS minification removes comments and whitespace. JavaScript minification removes comments and whitespace (lightweight regex-based, not AST-based — suitable for most sites).

Analytics

Traffic and bandwidth statistics collected from real proxy responses. Metrics include total bandwidth served, request count, cache hit rate, and error count — broken down by day for up to 90 days. The top 20 pages by bandwidth are also tracked.

Data starts accumulating as soon as the proxy serves requests. No external service or tracking script is involved — everything is stored locally in the SQLite database.

Notifications

Send real-time alerts to Telegram (via Bot API) or any Webhook URL when important events happen:

• Origin unreachable — the proxy can't connect to your origin
• Origin recovered — the origin became reachable again
• Rate limit exceeded — an IP hit the rate limit threshold
• License expiring — subscription/domain license is close to expiry

Notifications are throttled to at most once every 5 minutes per event type to prevent spam. Use Send Test Notification to verify your configuration before relying on it.

Error Pages

Define a fully custom HTML page for each HTTP error code: 403, 404, 429, 500, 502, 503. Leave a code empty to return a plain status code with no body. A "Load default template" button generates a minimal branded starting point you can customise.

Project Info

Read-only display of your Project Name and Origin URL, as configured in your .env file. To change these, edit .env and restart - they can't be changed from the admin panel.

System Active

The master kill switch for the entire proxy. Turn it off and every incoming request - cache, origin, license checks, everything - immediately returns 503 Service Unavailable, regardless of any other setting. The admin panel itself always stays accessible so you can turn it back on.

Rate Limiting

Limits how many requests a single IP can make within a time window (e.g. 100 requests per 60 seconds). Requests over the limit get an immediate 429 Too Many Requests. Only applies to real proxy traffic - the admin panel is never rate limited.

On-Demand Active

See On-Demand Rules above for the full explanation. This is where you turn the mechanism on/off and choose the fallback behavior.

Cache Priority & Origin Proxy Pool

See Cache Manager above.

Licensing

Sidien runs with no license at all as a free tier - core caching, redirects, page rules, user-agent & URL blocking, and rate limiting all work without a key. A handful of advanced features (Regex Rules, API Domains, On-Demand Active, Head/Element Injection, Data Capture) require a paid license and show a "Pro feature" lock screen in the admin panel until one is added.

This isn't just a configuration lock - if your license expires or is removed while you already have rules configured for these features, those rules stop being applied to real traffic immediately (they stay in the database, untouched). Add a valid license back and they re-activate automatically - no need to re-create or re-enable anything.

There are three paid license types:

• Domain - tied to one domain (+ all its subdomains), not tied to any IP/server. Requires setting both LICENSE_SERIAL and LICENSED_DOMAIN in your .env.
• Unlimited - not tied to any IP or domain. Fully portable, only checks that the subscription period hasn't expired.
• Lifetime - tied to a specific server's IP address (covers unlimited domains on that server), never expires.

Lifetime license checks verify that the serial key in your .env file (LICENSE_SERIAL) matches one of this machine's real, currently-bound network interface IP addresses - not a single fixed IP, so things like VPNs changing your "default route" don't break the license.

Domain licenses additionally check the incoming request's Host header against LICENSED_DOMAIN on every request - "example.com" covers "example.com" and any subdomain ("www.example.com", "api.example.com"), but not a different domain.

If you entered a license and it's invalid or expired, a red banner appears at the top of every admin panel page, and the proxy returns 423 Locked for all real traffic until it's fixed or removed. If you simply haven't entered a license, you'll instead see a neutral "Free tier" banner and the proxy keeps serving normally with Pro features locked. Check Settings → Project Info and the Dashboard's Server IP card to see what this server reports as its own address.

FAQ & Troubleshooting

I edited a rule but the change doesn't show up on the live site

Most content rules (Regex Rules, Head Injection, Element Injection) only re-run when a page is fetched fresh from your origin - not on cached page views. Clear that specific page's cache (or Clear All) from the Cache Manager to see the change immediately.

I locked myself out with an IP or User-Agent rule

You can't - these rules deliberately never apply to the admin panel itself, only to real site traffic. If you're unable to reach the admin panel, the cause is something else (wrong URL/port, System Active is off, or a firewall).

The proxy returns 423 Locked for everything

You've entered a license that's invalid, mistyped, or expired. See Licensing above. (If you haven't entered any license at all, this isn't the cause - that's the free tier, and traffic is served normally.)

The proxy returns 503 for everything

System Active is turned off. Go to Settings and turn it back on.

A visitor gets redirected somewhere unexpected after logging in / during checkout

Your origin is likely returning a redirect that Sidien is following internally instead of passing through to the browser. Add a Location Passthrough rule for that path.

↑ Back to top