cryload - Powerful HTTP Benchmarking Tool

cryload is a powerful, fast, and practical HTTP benchmarking tool for stress testing APIs and web services.

Built with Crystal for high performance and low overhead.

Why cryload?

• High-throughput HTTP load testing with a lightweight CLI experience
• Concurrent benchmarking with configurable connection count
• Request count mode (-n) and duration mode (-d) support
• Flexible request customization (method, headers, body, body-file, auth, user-agent, host header, timeout, TLS)
• JSON output mode for CI/CD and automation workflows
• Richer latency percentiles plus response/error breakdowns
• Optional global request rate limiting with --rate

Installation

Option 1: Install script (recommended)

Downloads the matching asset from Releases, verifies SHA256, and installs to ~/.local/bin (or %USERPROFILE%\.local\bin on Windows).

Linux / macOS (needs curl or wget, and sha256sum or shasum):

curl -sSfL https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.sh | sh -s

Install a specific version:

VERSION=v3.0.0 curl -sSfL https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.sh | sh -s

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.ps1 | iex

Option 2: Prebuilt binary

Download the latest prebuilt binary from the Releases page, then make it executable:

chmod +x cryload
./cryload --help

Option 3: Build from source

Requires Crystal 1.19.0 or later.

git clone https://github.com/sdogruyol/cryload.git && cd cryload
shards build --release

The binary will be at bin/cryload.

Quick Start

Run your first benchmark in seconds:

bin/cryload http://localhost:3000 -n 10000 -c 100

Usage

cryload <url> [options]

Options:

Examples:

10,000 requests to localhost

cryload http://localhost:9292 -n 10000

10 seconds with 100 connections

cryload http://localhost:3000 -d 10 -c 100

Simple POST request

cryload http://localhost:3000/api/login -n 1000 -m POST

POST with plain text body

cryload http://localhost:3000/api/echo -n 500 -m POST -H "Content-Type: text/plain" -b "hello"

POST with JSON body

cryload http://localhost:3000/api -n 500 -m POST -H "Content-Type: application/json" -b '{"name":"cry"}' --timeout 5

POST JSON body from file

cryload http://localhost:3000/api -n 500 -m POST -H "Content-Type: application/json" --body-file payload.json

POST with multiple headers

cryload http://localhost:3000/api -n 300 -m POST -H "Authorization: Bearer token123" -H "X-Request-ID: benchmark-1" -b '{"ok":true}'

Basic auth request

cryload http://localhost:3000/private -n 300 --basic-auth username:password

Custom User-Agent and Host header

cryload http://127.0.0.1:3000 -n 300 --user-agent cryload-test/1.0 --host-header api.internal

Duration mode + timeout

cryload http://localhost:3000/api -d 15 -c 50 --timeout 3

Rate-limited run at 100 requests/sec total

cryload http://localhost:3000/api -n 1000 -c 50 --rate 100

Follow redirects

cryload http://localhost:3000/redirect -n 100 -L

Treat redirects as success without following them

cryload http://localhost:3000/redirect -n 100 --success-status 200-299,302

HTTPS with self-signed cert (skip TLS verification)

cryload https://localhost:8443 -n 1000 --insecure

JSON output for automation/CI

cryload http://localhost:3000/api -n 1000 --json

CSV output for scripts

cryload http://localhost:3000/api -n 1000 --output-format csv

Quiet mode for exit-code-only checks

cryload http://localhost:3000/health -n 10 --output-format quiet

Example output:

Preparing to make it CRY for 10 seconds with 100 connections!
Running load test @ http://localhost:3000/
Mode: duration (10s)
Connections: 100
Rate limit: unlimited
Success statuses: 200-299

Summary
  Total requests: 1696170
  Total time: 10.11s
  Requests/sec: 167803.62
  Responses: 1696170
  Transport errors: 0 (0.0%)
  Fastest: 0.19 ms
  Slowest: 35.39 ms

Status
  Successful: 1696170 (100.0%)
  Failed: 0 (0.0%)
  Success statuses: 200-299

Transfer
  Total data: 374.14 MiB
  Size/request: 231.0 B
  Transfer/sec: 37.01 MiB/s

Latency (ms)
  avg: 0.53   min: 0.19   stdev: 0.76   max: 35.39

Latency Percentiles (ms)
  p50: 0.41   p90: 0.81   p95: 0.96
  p99: 1.34   p999: 3.72

Latency Histogram (ms)
  3.390 ms [120] |■■
  6.590 ms [420] |■■■■■■■
  9.790 ms [1690630] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■

Latency Distribution (ms)
  10.0% in 0.32
  25.0% in 0.38
  50.0% in 0.41
  75.0% in 0.55
  90.0% in 0.81
  95.0% in 0.96
  99.0% in 1.34
  99.9% in 3.72

Status Code Distribution
  [200] 1696170 responses (100.0%)

Built With Crystal

cryload is written in Crystal, combining Ruby-like developer ergonomics with compiled-language speed.

Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b my-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin my-feature)
5. Open a Pull Request

License

MIT