ScalWS
Get started
Get started

Start here

Getting started

https://scalws.com · daemon scalwsd · CLI scalwsctl · ScalWS Adaptive Runtime controller scalws-controller

A Linux-first web and application server written in Rust: fast, observable, secure and multi-tenant, with PHP, Node.js, Python and arbitrary upstreams as first-class runtimes.

Status: M10. All milestones of the handoff (M0–M10) and all acceptance gates are done: serving core, managed PHP-FPM / Node.js / Python / container runtimes, cgroup v2 tenancy, framework profiles, response cache (memory + disk), deterministic security and optimizer, diagnostics, optional local AI advisor, admin API (Unix socket, optional mTLS) with scalwsctl, ACME certificates, DEB/RPM packages for amd64 and arm64. Experimental and opt-in at build time: HTTP/3 (--features http3) and eBPF network accounting (--features ebpf). The multi-node control plane is designed (ADR-0021), not built.

What works today

  • HTTP/1.1 and HTTP/2 (ALPN and h2c prior knowledge), TLS 1.2/1.3 via rustls with SNI certificate selection (exact and wildcard)
  • Tenant → application → domain model; host routing (exact + *. wildcard); path routes matched on normalised paths
  • Handlers: confined static files (conditional + range requests), HTTP reverse proxy over TCP, TLS or Unix sockets with WebSocket tunnelling, fixed responses
  • Managed runtimes: PHP-FPM pools over FastCGI (front controller, PATH_INFO), Node.js processes, Python ASGI/WSGI servers (uvicorn, hypercorn, gunicorn) — supervised with readiness, crash backoff, restart-loop detection, graceful drain and log capture
  • Tenancy: cgroup v2 limits per tenant (CPU, memory, pids, I/O weight) with race-free worker placement and live updates; per-tenant concurrency and rate quotas; per-tenant and per-application resource accounting
  • Application profiles: scalwsctl detect /srv/app recognises WordPress, WooCommerce, Laravel, Next.js, Django, Flask, FastAPI and generic PHP/Node/Python apps, shows its evidence and proposes a configuration; profile: wordpress in config
  • Response cache (opt-in per app): explicit freshness only, Vary, stale-while-revalidate, profile bypass rules, purge by URL/prefix/tag
  • Security: profile deny rules (e.g. wp-config.php, .env), per-IP connection and request limits with bounded memory, write timeout for slow readers, strict SNI (421)
  • Optimizer: deterministic worker rules with cooldowns, bounds and automatic rollback; recommend-only unless autoscale: auto; audited (scalwsctl recommendations)
  • Diagnostics: correlated findings (crash loops, OOM kills, CPU/memory/I/O pressure, upstream timeouts, saturation, …) and recent failed/slow requests (scalwsctl diagnose)
  • ACME (HTTP-01) certificates with renewal without restart; trusted proxies (X-Forwarded-For, PROXY protocol); container applications (podman/docker)
  • Optional local AI advisor (off by default): explains diagnostics with an operator-chosen local model; redacted input, validated output, never acts (scalwsctl explain)
  • Operations: admin API on a Unix socket, scalwsctl (reload, rollback, diff, restart, scale, purge, top, backup/restore), read-only dashboard, DEB/RPM packages — see docs/OPERATIONS.md
  • Limits: connections, header size/count, URI length, body size, TLS handshake / header / body / idle timeouts, HTTP/2 stream and reset limits
  • Prometheus metrics (/metrics) and JSON access logs, bounded label cardinality
  • Validate-then-swap configuration reload (SIGHUP), restart-only topology changes rejected, graceful drain on SIGTERM
  • scalwsctl check runs the exact prepare path a reload would

Install

Ubuntu 24.04 or later, Debian 13 or later (amd64), from the signed ScalWS apt repository:

curl -fsSL https://scalws.com/apt/scalws-archive-keyring.gpg   -o /usr/share/keyrings/scalws-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/scalws-archive-keyring.gpg] https://scalws.com/apt stable main'   > /etc/apt/sources.list.d/scalws.list
apt update && apt install scalws
scalwsctl check && systemctl enable --now scalwsd

Configuration: /etc/scalws/scalws.yaml; console: https://<host>:8090 (see docs/OPERATIONS.md).

Quick start from source

cargo build --release
./target/release/scalwsctl check examples/scalws.yaml        # needs the referenced files
./target/release/scalwsd --config examples/scalws.yaml
kill -HUP $(pidof scalwsd)                            # reload
curl -s 127.0.0.1:9901/metrics | grep scalws_http_requests_total

Layout

crates/   scalws-core scalws-config scalws-runtime scalws-runtime-node scalws-runtime-python
          scalws-runtime-php scalws-router scalws-tls scalws-static scalws-proxy scalws-observe scalws-http
          scalws-server
cmd/      scalwsd (daemon), scalwsctl (CLI)
tests/    integration (end-to-end serving + security tests)
bench/    benchmark harness (Docker), bench upstream, nginx/caddy comparison configs
docs/     ARCHITECTURE.md, THREAT_MODEL.md, DECISIONS.md, adr/
examples/ configuration examples
profiles/ application profiles (YAML, embedded at build time)
packaging/systemd
docker/   test.Dockerfile (Linux test image with PHP-FPM, Node.js, Python servers)
scripts/  linux-test.sh, smoke.sh, profile.sh

Development

cargo test --workspace                 # any OS
scripts/linux-test.sh --docker         # authoritative Linux run (fmt, clippy, tests)
cargo deny check && cargo audit        # supply chain (CI runs both)

Benchmarks: see bench/README.md.