← back home · # architecture
recurl runs three layers in order, and each layer only runs if the previous one was blocked. The successful path is the cheapest one, every time — a request that plain curl handles never pays browser cost.
# each arrow to the right is an exit — recurl stops at the first layer that succeeds.
# the three layers
recurl execs upstream curl with every flag you passed. If the response is 2xx, recurl is done: total overhead is a single process boundary. This is the path the vast majority of requests take, and it costs nothing extra.
On a 403, 429, or recognised challenge, recurl retries through curl-impersonate with a browser-matching JA3/JA4 handshake, HTTP/2 SETTINGS frame, and pseudo-header order. Chrome, Firefox, Safari, and Edge profiles are available. Linux and macOS only.
If impersonation is still blocked, recurl spins up headless Chromium via the recurld daemon, solves the JS challenge, captures cookies, and replays the original request through curl. Windows skips straight here, since it has no impersonation layer.
# why this shape
Most traffic — APIs, JSON endpoints, downloads, status checks — never needs a browser. Paying Chromium overhead per request would be wasteful, so recurl only pays it when a request is actually blocked. See recurl vs curl for the overhead breakdown.
# recurld daemon
The recurld background daemon keeps a warm Chromium instance so repeated JS preflights are fast — the first request pays the boot cost, the next fifty do not. It shuts down after a configurable idle timeout. Tuning lives in the escalation guide.
Pass --recurl-debug to see which layer ran and why. Then read the full feature surface.