# GroundShade

> Self-hosted Rust reverse proxy that absorbs DDoS bursts and aggressive scraping. It stays invisible to real users until the origin starts hurting, then walls off the suspicious clients. Apache-2.0.

GroundShade installs behind your TLS terminator (Caddy, nginx, HAProxy) and reads each client on the wire. It reacts to origin health, not traffic volume: when p95 latency or 5xx rate climb, only suspect clients hit a SHA-256 proof-of-work wall. Verified search-engine crawlers are waved through, and API clients can solve the same challenge over a JSON envelope. Single Rust binary or a ~140 MB Docker image, in-memory state by default, no telemetry.

Each doc below links to its plain-markdown version. Every HTML page also has a `.md` twin at the same path (for example /docs/operating and /docs/operating.md).

## Docs

- [Getting started](https://groundshade.com/docs/getting-started.md): Drop GroundShade in behind Caddy, nginx, or HAProxy. Five minutes to a working request path.
- [Operating GroundShade](https://groundshade.com/docs/operating.md): Daily operator guide. Configuration, defense levels, fast-lane allowlists, the admin dashboard, the metrics reference, and the tuning table.
- [Deployment hardening](https://groundshade.com/docs/hardening.md): Pre-deploy security checklist. Admin port, trusted proxies, body limits, and reload safety. Read this once before publishing.
- [Behind Cloudflare](https://groundshade.com/docs/cloudflare.md): Running GroundShade behind Cloudflare orange-cloud. Required trusted_proxies, what works, what gets silenced, and the Caddy recipe.
- [Architecture](https://groundshade.com/docs/architecture.md): The mental model. Workspace shape, request lifecycle, in-memory state surfaces, concurrency model, and explicit non-goals.
- [Building from source](https://groundshade.com/docs/build.md): Build GroundShade locally or for production. Local Docker images, multi-arch builds, Cargo profiles, cache strategies, and image layout.
- [FAQ](https://groundshade.com/docs/faq.md): Common GroundShade questions. PoW choice, JA4 setup behind Caddy, dashboard exposure, Cloudflare compatibility, healthcheck cascades, and self-protection.

## Optional

- [llms-full.txt](https://groundshade.com/llms-full.txt): every doc concatenated into one file
- [SPEC.md](https://codeberg.org/groundshade/groundshade/src/branch/main/SPEC.md): byte-level wire formats and full design rationale
- [Source repository](https://codeberg.org/groundshade/groundshade): the Apache-2.0 codebase