DOCUMENTATION / PREVIEW 2026.10

Serve your first directory.

Superweb serves static files over HTTP/1.1, with optional TLS and HTTP/2. It runs native worker threads and caches small files and gzip responses in memory.

Install

The installer selects a build for your OS and CPU, verifies its SHA-256 checksum, and installs into ~/.local. It does not configure a service, open firewall ports, or require root.

curl -fsSLO https://superweb.to/install.sh
sh install.sh
export PATH="$HOME/.local/bin:$PATH"
superweb --help

The macOS archives require macOS 26 or later. The Apple Silicon build targets the M1 instruction set and includes OpenSSL and nghttp2 libraries; it was tested on an M5 Max. The Intel macOS archive requires AVX2 and serves HTTP/1.1 only. macOS binaries are signed ad hoc, not Apple-notarized; local security policy may restrict them. Linux ARM64 is built and tested on Ubuntu 24.04 (Graviton2); it needs the system libraries below.

# Ubuntu 24.04 ARM64 runtime dependencies
sudo apt-get install libssl3t64 libnghttp2-14 zlib1g

For a manual install, download your archive and SHA256SUMS, verify the archive, then extract it. Each archive includes an install.sh that accepts an optional installation prefix. Keep the bundled libraries beside the Apple Silicon binary.

# Linux example, after downloading both files
sha256sum --ignore-missing -c SHA256SUMS
tar -xzf superweb-linux-arm64.tar.gz
cd superweb-linux-arm64
sh install.sh "$HOME/.local"

Run

superweb --root ./public \
  --bind 127.0.0.1 --port 8080 \
  --workers 2

Visit http://127.0.0.1:8080/. Bind to 0.0.0.0 to accept remote connections. Use an explicit document root; only place files intended to be public there.

Configuration

Every option below can also appear in a config file as key=value. Load it with superweb --config server.conf. Boolean flags may appear on their own.

Option	Behavior
`--root DIR`	Directory to serve, with index.html for directories.
`--bind HOST --port N`	Listen address and HTTP port. Defaults: 127.0.0.1:8080.
`--workers N`	Worker threads. Each worker has its own bounded cache.
`--revalidate-ms N`	Time before checking the file version again. Default: 1000 ms. Set 0 to check on every request.
`--max-age SEC`	Set the response Cache-Control max-age. This is separate from the server's file cache.
`--access-log PATH`	Enable access logging. Disabled by default.
`--error-log PATH`	Write errors to a file.
`--redirect FROM=TO`	302 redirect. A FROM ending in / matches a prefix.
`--error-page 404=FILE`	Custom error document, relative to the document root.
`--cors ORIGIN`	Set a CORS origin.
`--autoindex`	Enable directory listings. Off by default.
`--auth USER:PASS`	Basic authentication. Use TLS; protect config-file permissions.
`--proxy PREFIX=HOST:PORT`	Forward to a cleartext HTTP upstream, stripping the prefix. Chunked request bodies are unsupported.

TLS and HTTP/2

Pass your certificate chain and private key to terminate TLS directly in Superweb. Supply both paths. Certificates are loaded at startup; restart the service after renewal.

superweb --root ./public --port 8080 \
  --tls-port 8443 \
  --tls-cert /path/to/fullchain.pem \
  --tls-key /path/to/privkey.pem

For local development, --tls without certificate paths creates a self-signed localhost certificate under certs/. This is not a publicly trusted certificate.

Cache behavior

Files up to 256 KiB can be held in memory. Each worker has 512 cache slots and a 32 MiB budget shared by original file bytes, gzip bytes, and complete HTTP/1 responses. Header templates can use up to roughly 1 MiB more per worker. Large files use file descriptors and sendfile over cleartext HTTP.

Gzip is computed once per cached file version, when requested. File changes invalidate both representations. Responses already in flight retain their bytes until the send completes. Server-side cache revalidation and browser Cache-Control are independent settings.

Benchmarking the comparison hosts

Each host serves the same public SiteVue snapshot on its own t4g.nano in us-east-2a, with two CPU workers and Ubuntu 24.04 ARM64. nginx and Caddy use precompressed gzip files; lighttpd uses its compression cache; Superweb uses its memory cache. Access logs are disabled for the comparison.

# Warm up first; repeat for all four hosts in alternating order.
wrk -t2 -c32 -d5s -H 'Accept-Encoding: gzip' \
  http://superweb.superweb.to/
wrk -t2 -c32 -d15s --latency -H 'Accept-Encoding: gzip' \
  http://superweb.superweb.to/

Substitute nginx, caddy, or lighttpd for the first hostname label. Use /benchmark/tiny.txt for a 14-byte response or select an identical asset path from the content manifest. Compare decoded response hashes, check status and socket errors, and report every round.

Use a separate load generator for server throughput. A client across the internet mostly measures the path between it and AWS. T4g instances are burstable; these hosts use Unlimited credits. Track CPU utilization, credit balance, surplus credits, memory, and network throughput. Sustained CPU load above the included baseline can incur additional AWS charges.

The AWS report uses the first three complete rounds of a planned five-round run from a separate c7g.xlarge in the same availability zone: four wrk threads, 64 connections, 2-second warmups, and 10-second measurements. It preserves response hashes, latency, errors, CPU use, network counters, and credit metrics. Round four stopped when Superweb fell to the network baseline and recorded nine timeouts. All 78 samples remain public; the chart uses the 60 measurements in the three common complete rounds. These are burst results. The earlier M5 Max report uses different hardware, versions, and payloads.

For repeatable multi-round runs, download the standalone Linux driver and public-host config. It requires Python 3, ethtool, and wrk 4.2.0. Public-host runs include the internet path from your client; record its hardware and location.

CPU and RAM at the limit

The main chart includes CPU, available host RAM, bandwidth, and inferred limits from the original throughput run. A separate resource study measures the current services with one-second sampling, three rounds, and five-second load tests. Its request rates and network-credit state are reported separately.

100% CPU means both vCPUs are busy. Service CPU covers the server's processes; host CPU includes other processes and kernel/network work. Server RAM is the sampled peak proportional set size (PSS) of all worker processes, so shared resident pages count proportionally. Available host RAM is a different measurement. Raw data also contains RSS, swap, cgroup memory including charged page cache, errors, and bandwidth-allowance counters. These short tests do not establish a maximum memory capacity.

Compare in your browser

Open the timed preview to load the same public SiteVue page from each server. Choose a host or use “Run all four” for a shuffled sequential comparison. The header times navigation until the iframe’s load event. Each card shows the median of that server’s completed runs in the current tab; results are not uploaded.

This includes browser and network costs, and browser caches remain active. Lazy images, subsequent fetches, and 3D scenes may finish after the load event. Hidden-tab runs are excluded. Cross-origin iframe load events cannot prove successful page delivery: check the rendered preview and clear results if it shows an error. Use the AWS throughput report for a controlled server comparison.

Scope

The comparison hosts serve public static SiteVue pages. Authentication, internal qualification tools, campaigns, and gated pages remain on the original SiteVue site. External lead submission uses SiteVue's production API, whose CORS policy may not allow mirror origins; use the original site for real submissions.

Superweb is a preview. It does not currently support HTTP/3, Brotli, multipart ranges, virtual hosts, or upstream HTTPS. WebSocket proxying occupies a worker. The bundled Intel build has no TLS. Stop the server with SIGTERM or Ctrl-C; SIGHUP reopens log files.