---
url: /guide.md
description: >-
  Set up Cap, the open-source self-hosted CAPTCHA, in about five minutes. Run
  the server with Docker, drop in the widget, verify tokens. No Google, no
  telemetry, no visual puzzles.
---

# Quickstart

cap is a self-hosted and privacy-first captcha alternative that doesn't force your users to click on traffic lights. there are no puzzles, no tracking, and no third parties watching your visitors.

cap has two parts: a **widget** that runs the challenge and shows the checkbox, and a **server** that issues challenges and verifies solutions. you'll have both running in about five minutes.

::: tip Already using reCAPTCHA?
Cap's `/siteverify` is compatible with reCAPTCHA's API. You can point your existing verification code at Cap by changing one URL, run both side by side, and cut over whenever you're ready. There's no rewrite and no risky big-bang switch. See the [feature comparison](./alternatives.md).
:::

## What you'll need

* [Docker](https://docs.docker.com/get-docker/) (the fastest way to run the server)
* A place to host it that's reachable from your users' browsers
* A few minutes

## 1. Run the server

I recommend [Cap Standalone](./standalone/index.md), a single container that exposes a small REST API and a dashboard for managing keys. It supports multiple site keys and is compatible with reCAPTCHA's siteverify API.

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/cap-1?referralCode=93HYBZ\&utm_medium=integration\&utm_source=template\&utm_campaign=generic)

Create a `docker-compose.yml`:

```yaml
services:
  cap:
    image: tiago2/cap:latest
    container_name: cap
    ports:
      - "3000:3000"
    environment:
      ADMIN_KEY: your_secret_password
      REDIS_URL: redis://valkey:6379
    depends_on:
      valkey:
        condition: service_healthy
    restart: unless-stopped

  valkey:
    image: valkey/valkey:9-alpine
    container_name: cap-valkey
    volumes:
      - valkey-data:/data
    command: valkey-server --save 60 1 --loglevel warning --maxmemory-policy noeviction
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  valkey-data:
```

Start it:

```bash
docker compose up -d
```

Open `http://localhost:3000` (or your server's IP or domain on port 3000), log in with your `ADMIN_KEY`, and create a site key. You'll get a **site key** and a **secret key**. Keep both, you'll need them in the next steps.

::: tip Tips

* `ADMIN_KEY` is your dashboard password. Make it at least 32 characters.
* Change `3000:3000` if that port is already in use.
* If the dashboard is unreachable, add `network_mode: "host"` under the `cap` service.
  :::

## 2. Add the widget

The widget is a single web component. If you wouldn't like to pin versions, replace `<version>` with `latest`.

```html
<script src="https://cdn.jsdelivr.net/npm/cap-widget@<version>"></script>
```

::: tip
Check the [latest release](https://github.com/tiagozip/cap/releases) for the version to pin. You can also [self-host the widget](./widget.md#self-hosting-the-widget), serving both the script and the solver's WASM files from your own domain instead of the CDN.
:::

### The simple way: drop it in a form

If your widget lives inside a `<form>`, Cap injects a hidden `cap-token` field automatically and submits it with the rest of your form data. No JavaScript required.

```html
<form action="/submit" method="POST">
  <!-- your fields -->
  <cap-widget data-cap-api-endpoint="https://<your-instance>/<site-key>/"></cap-widget>
  <button type="submit">Submit</button>
</form>
```

* `<your-instance>` is the public URL of your Cap server, e.g. `cap.example.com`. It has to be reachable by your visitors, so not `localhost`.
* `<site-key>` is the site key from your dashboard.

On submit, your server receives `cap-token` alongside the other fields. Skip to [step 3](#_3-verify-the-token) to verify it.

### With JavaScript: when you need control

For SPAs, custom flows, or anything that isn't a plain form, listen for the `solve` event:

```js
const widget = document.querySelector("cap-widget");
widget.addEventListener("solve", (e) => {
  const token = e.detail.token;
  // send token to your server, enable the submit button, etc.
});
```

You can also render the widget invisibly and solve [programmatically](./programmatic.md), or use [floating mode](./floating.md). Framework snippets (React, Vue, Svelte and more) are on the [widget page](./widget.md#usage).

## 3. Verify the token

Before you trust a submission, your server has to verify the token. Send a `POST` to your instance's `/siteverify` endpoint:

::: code-group

```sh [curl]
curl "https://<your-instance>/<site-key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'
```

```js [fetch]
const { success } = await (
  await fetch("https://<your-instance>/<site-key>/siteverify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ secret: "<key_secret>", response: "<captcha_token>" }),
  })
).json();

if (!success) throw new Error("invalid cap token");
```

```py [python]
import requests

success = requests.post(
    "https://<your-instance>/<site-key>/siteverify",
    json={"secret": "<key_secret>", "response": "<captcha_token>"},
).json().get("success")
```

```php [php]
<?php
$data = json_decode(file_get_contents("https://<your-instance>/<site-key>/siteverify",
  false, stream_context_create([
    "http" => [
      "method" => "POST",
      "header" => "Content-Type: application/json",
      "content" => json_encode(["secret"=>"<key_secret>","response"=>"<captcha_token>"])
    ]
  ])
), true);
var_dump($data['success'] ?? false);
```

:::

* `<key_secret>` is the **secret key** from your dashboard, not the dashboard `ADMIN_KEY`. Mixing these up is the most common setup mistake.
* `<captcha_token>` is the token from the widget (the `cap-token` form field or `e.detail.token`).

A valid token returns:

```json
{ "success": true }
```

Tokens are single-use, so verify each one once and then run your own logic (create the account, send the message, and so on).

## 4. Confirm it works

A quick end-to-end check:

1. Load your page. The checkbox should tick and your `solve` handler (or form field) should produce a token.
2. Send that token to `/siteverify`. You should get `{ "success": true }`.
3. Send the same token again. It should now fail, which confirms single-use is working.

If verification always fails, check that you're using the secret key (not the admin key) and that `<your-instance>` is the same public URL the widget points at.

That's the whole integration. Users solve challenges in their browser, your server verifies tokens, and you keep every byte of the data.

## Built for compliance

Because Cap is self-hosted with no cookies, no tracking, and no third-party calls, your users' data never leaves your infrastructure. Cap is designed to meet GDPR, CCPA, HIPAA, LGPD and other privacy regimes, and the proof-of-work checkbox avoids the WCAG 2.2 barriers that image and audio puzzles run into. Full details, and the regulations Cap is built around, are on the [Compliance](./compliance.md) page.

## Next steps

You're protecting your forms. From here you can:

* Drop Cap into your stack with a [framework snippet](./widget.md#usage)
* [Customize the widget](./widget.md#options)'s look and behavior
* Tune [instrumentation](./instrumentation.md) and [configure](./standalone/options.md) CORS and rate limiting
* See how Cap compares to [reCAPTCHA, Turnstile, hCaptcha and others](./alternatives.md)
* Read the [best CAPTCHA alternatives for 2026](./best-captcha-alternatives.md) guide if you're still evaluating

---

---
url: /guide/alternatives.md
description: >-
  Compare Cap against reCAPTCHA, hCaptcha, Turnstile, Altcha and more. See how
  the open-source, self-hosted, proof-of-work CAPTCHA stacks up on privacy and
  cost.
---

# CAPTCHA Feature Comparison: Cap vs the Alternatives

Cap is a free, open-source, self-hosted CAPTCHA alternative that uses proof-of-work and [instrumentation challenges](./instrumentation.md) instead of image puzzles. Here is how it compares to reCAPTCHA, hCaptcha, Cloudflare Turnstile, Altcha, FriendlyCaptcha, SilentShield, and others across 12 criteria.

| CAPTCHA              | Open-source | Free | Private | Fast to solve | Easy for humans | Small error rate | GDPR compliant | Customizable | Hard for bots | Instrumentation | RSW support | Easy to integrate |
| :------------------- | :---------- | :--- | :------ | :------------ | :-------------- | :--------------- | :------------- | :----------- | :------------ | :-------------- | :---------- | :---------------- |
| **Cap**              | ✅          | ✅   | ✅      | ✅            | ✅              | ✅               | ✅             | ✅           | ✅            | ✅              | ✅          | ✅                |
| Cloudflare Turnstile | ❌          | ✅   | 🟨      | 🟨            | ✅              | ❌               | ✅             | ❌           | ✅            | ✅              | 🟨          | ✅                |
| reCAPTCHA            | ❌          | 🟨   | ❌      | ❌            | ❌              | 🟨               | 🟨             | ❌           | 🟨            | ✅              | 🟨          | ✅                |
| hCAPTCHA             | ❌          | 🟨   | 🟨      | ❌            | ❌              | 🟨               | 🟨             | ❌           | 🟨            | ✅              | 🟨          | ✅                |
| Altcha               | ✅          | ✅   | ✅      | ✅            | ✅              | ✅               | ✅             | ✅           | 🟨            | ❌              | ❌          | 🟨                |
| FriendlyCaptcha      | ❌          | ❌   | ✅      | ✅            | ✅              | ✅               | ✅             | ✅           | ❌            | ❌              | ❌          | 🟨                |
| SilentShield         | ❌          | 🟨   | 🟨      | ✅            | ✅              | 🟨               | ✅             | ❌           | 🟨            | ✅              | ❌          | ✅                |
| MTCaptcha            | ❌          | 🟨   | 🟨      | ❌            | ❌              | 🟨               | ✅             | ❌           | ❌            | ❌              | ❌          | 🟨                |
| GeeTest              | ❌          | ❌   | ❌      | 🟨            | 🟨              | 🟨               | ✅             | ❌           | 🟨            | ❌              | ❌          | 🟨                |
| Arkose Labs          | ❌          | ❌   | ❌      | ❌            | ❌              | ❌               | ✅             | 🟨           | 🟨            | 🟨              | 🟨          | 🟨                |

One criterion Cap deliberately fails: there is no managed hosting. If you refuse to run any infrastructure at all, Cloudflare Turnstile or FriendlyCaptcha is a better fit.

::: tip Note

Based on internal testing, Cap achieved lower challenge abandonment rates and higher privacy-browser compatibility than competing solutions.

"Hard for bots" refers to resistance against commodity automation, including headless browsers, scripted attacks, and self-operated bot networks. For Cap, this is primarily provided by PoW and instrumentation. This category does not consider commercial CAPTCHA-solving services or human-assisted solver platforms, as their effectiveness is difficult to independently verify.
:::

## All alternatives

### Cloudflare Turnstile

Cloudflare Turnstile is a great alternative to Cap, but it is widely reported to fail or loop for users on privacy browsers such as Brave or Librewolf, because its verdicts rely on fingerprinting signals those browsers deliberately break.

Additionally, unlike Turnstile, Cap is open-source and self-hosted. With Turnstile, if Cloudflare's algorithm marks a user as "suspicious," you cannot override it. Cap puts the levers of control in your hands, so you decide the difficulty and strictness, not a third party.

[Full comparison: Cap vs Cloudflare Turnstile →](./alternatives/turnstile.md)

### reCAPTCHA

Not only is Cap significantly smaller and faster than reCAPTCHA, it's open-source, fully free, and much more private. Cap doesn't require you to check traffic signs or solve puzzles, and it doesn't track users or collect data.

reCAPTCHA v2 ("I'm not a robot") is getting harder for humans while remaining trivial for AI solvers (especially audio challenges). v3 (Invisible) is great, but if Google thinks you are "suspicious" (e.g., using a VPN or privacy tools), it often blocks you entirely or forces a hard puzzle loop with no way out.

[Full comparison: Cap vs reCAPTCHA →](./alternatives/recaptcha.md)

### hCAPTCHA

Pretty much the same as reCAPTCHA, however, while it's significantly more resistant to bots, it imposes a heavy "Puzzle Tax" on your users.

Users hate puzzles. They leave. Drop-off rates on hCaptcha challenges can be **5-15%** depending on difficulty. Additionally, hCaptcha's free tier is aggressive with serving puzzles to save their own costs, which hurts your conversion rates.

[Full comparison: Cap vs hCaptcha →](./alternatives/hcaptcha.md)

### Altcha

Cap is slightly smaller than Altcha and includes extra features like progress tracking, instrumentation challenges, and a simpler dashboard. If you don't need these, Altcha is still a solid choice.

[Full comparison: Cap vs Altcha →](./alternatives/altcha.md)

### mCAPTCHA

While mCAPTCHA is similar to both Cap and Altcha, it is still pre-1.0 with infrequent releases and has a larger widget bundle.

### FriendlyCaptcha

Unlike FriendlyCaptcha, Cap is completely free and self-hosted at any volume (FriendlyCaptcha's Starter plan is €9/month for 1,000 requests/month, with higher tiers as you scale).

[Full comparison: Cap vs FriendlyCaptcha →](./alternatives/friendlycaptcha.md)

### SilentShield

SilentShield is a hosted, invisible bot-protection service that scores mouse, keyboard, and scroll behavior instead of running a challenge. It's convenient on WordPress, but it's closed-source, can't be self-hosted, and its free tier caps at 500 requests/month (paid tiers from €9/month for 5,000 requests).

Cap imposes a real computational cost on bots rather than guessing from behavior, is fully open-source, and is free at any volume on your own infrastructure.

[Full comparison: Cap vs SilentShield →](./alternatives/silentshield.md)

### MTCaptcha

MTCaptcha relies heavily on image challenges, which are usually easily solvable by LLMs and OCRs and have high drop-off rates. Cap is also lightweight, self-hostable and doesn't rely on obfuscation.

### GeeTest

Cap is free, self-hosted, and open-source, while GeeTest is a paid service. Cap is also more private and doesn't rely on tracking users or collecting data. GeeTest is also China-based, which may be a concern for some users regarding data sovereignty.

### Arkose Labs

Arkose's CAPTCHA is known for being hard, slow, and annoying for humans to solve. It is also a paid, closed-source service mostly available to big enterprises.

They also only operate in the US, Canada, Argentina, India, Israel and a small set of other countries, excluding many EU countries.

### Anubis

While Anubis is a great scraper deterrent and uses the same proof-of-work concept as Cap, it uses a low difficulty by default (which is easier for bots to solve) and does not provide a standalone CAPTCHA server.

Cap also implements dynamic instrumentation challenges, which make it harder for bots to finish the process after solving PoW.

[Full comparison: Cap vs Anubis →](./alternatives/anubis.md)

## Related guides

* [Best CAPTCHA alternatives in 2026](./best-captcha-alternatives.md): the full field, ranked with criteria
* [Open-source CAPTCHA options](./open-source-captcha.md): Cap, ALTCHA, mCAPTCHA, and Anubis compared
* [CAPTCHA and conversion rate](./captcha-conversion-rate.md): how challenges cost you signups
* [Bot protection for mobile forms](./mobile-form-bot-protection.md): puzzle-free protection on touch devices
* [Migrate from reCAPTCHA](./alternatives/migrate-from-recaptcha.md): the URL-swap migration path

---

---
url: /guide/alternatives/migrate-from-recaptcha.md
description: >-
  Google is moving reCAPTCHA into Google Cloud and auto-migrating Classic keys.
  Migrate to Cap instead: a faster, private, self-hosted, open-source CAPTCHA
  with a reCAPTCHA-compatible siteverify API and Turnstile-tier bot detection.
---

# Migrating from reCAPTCHA to Cap

Google is moving reCAPTCHA into Google Cloud and auto-migrating Classic keys onto billed projects. So you have to touch your integration regardless. The good news: this is the perfect excuse to leave Google's tracking-based CAPTCHA behind for something faster, private, and free.

Cap is a drop-in replacement for the part that matters, and an upgrade for almost everything else.

## Why teams switch to Cap

* **Turnstile-tier detection, without the third party.** Cap pairs proof-of-work with instrumentation challenges, the same browser-verification technique YouTube and Twitter/X run at massive scale. It sits in the same detection tier as Cloudflare Turnstile while staying fully self-hosted.
* **Proven at scale.** Around **1 billion challenges solved in Q1 2026 alone** (per JSDelivr), and trusted in production by teams like **AdGuard** and **Bunny.net**. This is not an experiment.
* **A fraction of the weight, and invisible.** Cap's widget is roughly 21 KB gzipped versus reCAPTCHA's 200 to 600 KB client, often a 10x or more reduction. Default challenges solve in 2 to 3 seconds in the background, with no traffic-light puzzles and nothing for the user to click through.
* **Genuinely free, no metering.** No Google Cloud project, no billing account, no per-assessment fee. One Docker container and a Valkey instance run most workloads on a $5 VPS.
* **Private by default.** reCAPTCHA loads scripts from `google.com` and ships user signals to Google. Cap sends data nowhere. Nothing third-party touches your page.
* **You hold the controls.** reCAPTCHA v3 silently penalizes users on VPNs, Tor, and privacy browsers with no recourse. With Cap you set the difficulty, and every real user always has a path through.
* **Open source, forever.** Apache 2.0. Audit it, fork it, deploy it. No vendor can change the terms on you.

For the full breakdown, see [Cap vs reCAPTCHA](./recaptcha.md).

## What's changing with reCAPTCHA

If you need the context for why the migration emails are landing now:

* New keys can no longer be created in the legacy reCAPTCHA admin console.
* Existing reCAPTCHA Classic keys are being migrated automatically into Google Cloud projects, a process Google ran through late 2025 and into 2026.
* Once migrated, a key's API access is tied to a Google Cloud project. Past the free tier of 10,000 assessments per month, you have to enable billing on that project.

Keeping reCAPTCHA now means a Google Cloud project, a billing account on file, and metered assessments. Moving to Cap means none of that, on a timeline you control.

## How the migration works

Cap's `/siteverify` endpoint mirrors reCAPTCHA's request shape on purpose, so the server side is close to a drop-in. The widget swap is tag-for-tag. Three steps, and you can run both in parallel during the cut-over.

### 1. Stand up a Cap instance

Follow the [quickstart](../index.md) to run Cap Standalone with Docker. Create a site key in the dashboard and note both the **site key** and its **secret key**. Keep [instrumentation challenges](../instrumentation.md) on (the default) for the strongest bot protection.

### 2. Swap the client widget

Replace the reCAPTCHA script and element with Cap's widget.

Before:

```html
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="<your-recaptcha-site-key>"></div>
```

After:

```html
<script src="https://cdn.jsdelivr.net/npm/cap-widget"></script>
<cap-widget data-cap-api-endpoint="https://<your-instance>/<site-key>/"></cap-widget>
```

If your reCAPTCHA widget lived inside a `<form>`, the token handling carries over: reCAPTCHA auto-injected a `g-recaptcha-response` field, and Cap auto-injects a `cap-token` field on submit. Outside a form, listen for the `solve` event:

```js
document.querySelector("cap-widget").addEventListener("solve", (e) => {
  const token = e.detail.token;
});
```

### 3. Swap the server verification

reCAPTCHA verification posts `secret` and `response` to a fixed Google URL. Cap takes the same two parameters, posted to your own instance:

Before:

```js
const { success } = await (
  await fetch("https://www.google.com/recaptcha/api/siteverify", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ secret: RECAPTCHA_SECRET, response: token }),
  })
).json();
```

After:

```js
const { success } = await (
  await fetch("https://<your-instance>/<site-key>/siteverify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ secret: CAP_SECRET, response: token }),
  })
).json();
```

The token your server reads also changes name: pull `cap-token` from the submitted form (or the value you captured from the `solve` event) instead of `g-recaptcha-response`.

## What's compatible, and what isn't

We'd rather you migrate with eyes open than hit a surprise in production. The compatibility is real, but not byte-for-byte:

| | reCAPTCHA | Cap |
| --- | --- | --- |
| Request params | `secret`, `response`, optional `remoteip` | `secret`, `response` (`remoteip` is ignored) |
| Endpoint | fixed `google.com` URL | your own `/<site-key>/siteverify` |
| Success field | `success` (boolean) | `success` (boolean) |
| Error reporting | `error-codes` (array) | `error` (string) |
| Extra fields | `challenge_ts`, `hostname`, `score` (v3) | none |

In practice:

* Code that only checks `response.success` works after a URL and secret swap. That's the common case, and it's a one-line change.
* Code that inspects `error-codes`, `challenge_ts`, `hostname`, or the v3 `score` needs updating. Cap is a verification system, not a behavioral risk score, so those fields don't exist.
* If you use a backend SDK that hardcodes Google's verify URL, swap it for one that lets you set the endpoint, or call `/siteverify` directly. It's two parameters.

## Migrate with zero downtime

You never have to flip a switch and pray. Mount Cap on a separate element and have your backend accept either a valid `cap-token` or a valid `g-recaptcha-response` during the transition. Watch Cap's verification rate in your logs, and once it looks healthy, delete the reCAPTCHA script, element, and server call. Most teams finish the cut-over in an afternoon.

## See also

* [Live demo](../demo.md) — solve a Cap challenge yourself, then time it against reCAPTCHA
* [Cap vs reCAPTCHA](./recaptcha.md) — the full comparison
* [How Cap detects bots](../effectiveness.md) — the proof-of-work + instrumentation model
* [Quickstart](../index.md) — stand up Cap from scratch in five minutes

---

---
url: /guide/alternatives/recaptcha.md
description: >-
  Cap vs Google reCAPTCHA v2 and v3: a privacy-first, self-hosted, open-source
  alternative. No Google tracking or visual puzzles, just proof-of-work
  challenges.
---

# Cap vs reCAPTCHA

reCAPTCHA is Google's CAPTCHA service, available in two main versions: v2 ("I'm not a robot") and v3 (invisible, score-based). Both require sending traffic data to Google.

## Quick verdict

If your site doesn't already depend on Google for analytics or login, there is little reason to keep reCAPTCHA. Cap matches the protection level for the vast majority of use cases without sending users to Google, without per-request quotas, and without forcing visitors through traffic-light puzzles when Google's risk score doesn't like them.

## Where reCAPTCHA still makes sense

* You're already deeply integrated with Google's identity stack and want one less vendor decision.
* You specifically need Google's behavioral risk score (v3) and have the infrastructure to act on it.
* Your team is unwilling to run any backend service, even a single Docker container.

## Where Cap is the better choice

* **Privacy.** reCAPTCHA loads scripts from `google.com` and sends user signals to Google. Cap runs entirely on your infrastructure and adds nothing third-party to your page.
* **No visual puzzles.** reCAPTCHA v2 routinely drops users into traffic-light, fire-hydrant, and crosswalk puzzles. These are increasingly easy for AI solvers and increasingly hard for humans, especially on mobile or for users on VPNs and privacy browsers.
* **Bundle size.** reCAPTCHA's client weighs 500 KB+. Cap's widget is ~20 KB.
* **No quotas.** reCAPTCHA Enterprise is metered per assessment. Cap has no per-request fee: it runs on a $5 VPS for most workloads.
* **No "suspicious user" lockouts.** v3 will silently penalize users who use Tor, VPNs, or privacy-respecting browsers. With Cap you set the difficulty; the user always has a path through.
* **Open source.** Apache 2.0. Audit, fork, deploy.

## Migration

Cap's `/siteverify` endpoint is intentionally compatible with reCAPTCHA's API shape, so most server-side migrations are a single URL swap plus a new secret. Client-side, replace the `<script src="https://www.google.com/recaptcha/api.js">` and `<div class="g-recaptcha">` with Cap's widget; see the [quickstart](../index.md) for a full walk-through.

You can also run them side-by-side during the cut-over by mounting Cap on a different element and verifying both tokens server-side until you're confident.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): the proof-of-work + instrumentation model
* [All alternatives](../alternatives.md): full feature matrix
* [Best CAPTCHA alternatives in 2026](../best-captcha-alternatives.md): every reCAPTCHA alternative, ranked
* [CAPTCHA and conversion rate](../captcha-conversion-rate.md): what puzzle loops cost your signups

---

---
url: /guide/alternatives/turnstile.md
description: >-
  Cap vs Cloudflare Turnstile: a self-hosted, customizable, open-source CAPTCHA
  you fully control. No vendor lock-in, with proof-of-work and instrumentation.
---

# Cap vs Cloudflare Turnstile

Turnstile is Cloudflare's free CAPTCHA replacement, focused on running invisible challenges that lean heavily on Cloudflare's network signals and browser fingerprinting.

## Quick verdict

Turnstile is genuinely good if you're already on Cloudflare and accept that the verdict is theirs to make. Cap is the better fit when you want self-hosting, deterministic difficulty, no third-party dependency, and the ability to override decisions for your own users.

## Where Turnstile makes sense

* You're already routing traffic through Cloudflare and want to stay in one ecosystem.
* You don't want to host anything; Turnstile is fully managed.
* You're willing to accept Cloudflare's algorithmic decisions for "suspicious" visitors with no way to override.

## Where Cap is the better choice

* **Self-hosted.** Cap runs on your servers. Turnstile requires every challenge to round-trip through Cloudflare.
* **You own the policy.** With Turnstile, if Cloudflare's algorithm decides a user looks suspicious (common for Brave, Librewolf, Tor, or VPN users), there is no override. Cap puts the difficulty knob in your hands.
* **Lower error rate for privacy-conscious users.** Turnstile is widely reported to misclassify hardened browsers. Cap's proof-of-work doesn't care about fingerprints.
* **Open source.** Apache 2.0 vs Turnstile's closed-source client and server.
* **No telemetry.** Cap doesn't phone home and doesn't set cookies. Turnstile's client communicates with `challenges.cloudflare.com` on every page load.
* **Customizable.** Cap exposes CSS variables for colors, size, and shape. Turnstile's iframe is mostly fixed.

## Where they're similar

Both ship a small (~20-110 KB) client. Both run an "invisible" mode (Cap calls it [floating mode](../floating.md) or [programmatic mode](../programmatic.md)). Both layer behavioral checks on top of a primary challenge: Cap calls those [instrumentation challenges](../instrumentation.md), Turnstile calls them "managed challenges."

## Migration

Cap's `/siteverify` API shape is compatible with Cloudflare's `siteverify`, so server-side verification is mostly a URL and secret swap. The client-side change is replacing `<div class="cf-turnstile">` with `<cap-widget>` and pointing it at your Cap instance; see the [quickstart](../index.md) for full code.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): proof-of-work + instrumentation
* [All alternatives](../alternatives.md): full feature matrix
* [Best CAPTCHA alternatives in 2026](../best-captcha-alternatives.md): Turnstile, Cap and the rest of the field ranked
* [Bot protection for mobile forms](../mobile-form-bot-protection.md): where fingerprint signals fail hardest

---

---
url: /guide/alternatives/hcaptcha.md
description: >-
  Cap vs hCaptcha: a self-hosted, puzzle-free, open-source CAPTCHA alternative.
  No image grids, no data sold to advertisers, free at scale via proof-of-work.
---

# Cap vs hCaptcha

hCaptcha is the privacy-positioned, puzzle-based competitor to reCAPTCHA. The free tier shows image puzzles aggressively; the paid Pro tier ($99/mo annual, $139/mo monthly, 100k evaluations) unlocks a mostly-passive mode and analytics. It's the most aggressive of the major CAPTCHAs about visible puzzles on the free plan.

## Quick verdict

If you're using hCaptcha primarily because you wanted to leave Google, Cap is the simpler step. You don't trade Google for a different third party; you stop having a third party at all. And you stop charging your users a "puzzle tax" on every form submission.

## Where hCaptcha makes sense

* You specifically need hCaptcha Enterprise's threat-intel feed and risk-scoring at scale, and you have the budget for it.
* You're already deeply integrated and the migration cost outweighs the benefits.
* Your compliance program specifically requires a visible-puzzle human-verification step for regulated actions.

## Where Cap is the better choice

* **No image puzzles.** hCaptcha's drop-off rate on puzzles ranges from **5% to 15%** depending on difficulty. That's real conversion you're losing on signups, checkouts, and contact forms. Cap never shows a puzzle. (Hcaptcha Pro's passive mode reduces this, but it's a paid plan.)
* **Bundle size.** hCaptcha's client is 600 KB+. Cap is ~20 KB, about 30× smaller.
* **No quota or overage.** hCaptcha Pro starts at $99/mo for 100k evaluations and bills $0.99 per 1k after that. Cap is free at any scale, runs on a $5 VPS, no per-request fee.
* **Self-hosted.** No third-party dependency. Cap doesn't load anything from `hcaptcha.com`.
* **No fingerprinting.** hCaptcha relies on browser fingerprints and behavioral signals; that hurts users on privacy browsers. Cap's proof-of-work works the same regardless of browser.
* **Open source.** Apache 2.0. Audit it, run it on air-gapped infra, fork it.

## Where they're similar

Both run an instrumentation/behavioral layer in addition to the visible challenge. Both have invisible modes available. Both work with the standard form-submission pattern.

## Migration

Cap's `/siteverify` is API-shape compatible with hCaptcha's. Most backend changes are a URL swap. On the client, replace `<div class="h-captcha">` and `https://js.hcaptcha.com/1/api.js` with Cap's `<cap-widget>`; see the [quickstart](../index.md).

If you want to migrate gradually, run Cap on new forms first, keep hCaptcha on legacy ones, and watch the conversion delta.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): proof-of-work + instrumentation
* [All alternatives](../alternatives.md): full feature matrix
* [CAPTCHA and conversion rate](../captcha-conversion-rate.md): the full math behind the puzzle tax
* [Best CAPTCHA alternatives in 2026](../best-captcha-alternatives.md): puzzle-free options ranked

---

---
url: /guide/alternatives/altcha.md
description: >-
  Cap vs Altcha: two open-source, self-hosted proof-of-work CAPTCHAs compared.
  See how Cap adds instrumentation challenges, a widget, and a managed
  dashboard.
---

# Cap vs Altcha

Altcha is the closest project in spirit to Cap: open-source, proof-of-work, no fingerprinting, no third-party dependency. Both are good choices. The differences come down to features and operational shape.

Altcha also has a commercial product called **Altcha Sentinel** that layers ML-based threat detection on top of the open-source widget. The comparison below is mostly between Cap and the open-source Altcha widget; if you're considering Sentinel, you're comparing a paid SaaS to a self-hosted OSS project, which is a different decision.

## Quick verdict

If you want a minimal, library-style PoW CAPTCHA you can drop into a Node project and forget about, the open-source Altcha is great. If you want a turn-key self-hosted service with a dashboard, multi-site-key support, instrumentation challenges layered on top of PoW, and a UI that progress-tracks the solve (without paying for Sentinel), Cap is the better fit.

## Where Altcha makes sense

* You want a tiny, library-only integration with no separate service to run.
* You don't need a second verification layer beyond proof-of-work, or you're willing to pay for Sentinel to get ML-based detection.
* You're already integrated with Altcha and the migration cost outweighs the differences below.

## Where Cap is the better choice

* **Two independent verification layers, free.** Cap runs proof-of-work *and* dynamic JavaScript [instrumentation challenges](../instrumentation.md) in parallel, both included. Defeating one doesn't defeat the other. The open-source Altcha is PoW only; the second layer (ML-based) requires paying for Sentinel.
* **Standalone server with dashboard, free.** Cap ships a one-Docker-container deployment with a web dashboard, multi-site-key management, analytics, and a reCAPTCHA-compatible siteverify endpoint. Altcha's open-source side leaves you to wire those yourself; the all-in-one experience is Sentinel-only.
* **Smaller widget.** Cap is ~20 KB. Altcha is ~34 KB gzipped.
* **Progress tracking.** Cap's widget reports solve progress to the user as a percentage, meaningful UX feedback during the small wait.
* **Floating and programmatic modes.** Cap can hide entirely or float over a button until form submit. Altcha's display modes are simpler.
* **Customizable look.** Cap exposes CSS variables for colors, size, position, and icons. Altcha's customization is more limited.

## Where they're similar

* Both are open-source (Cap is Apache-2.0, Altcha's widget is MIT) with no telemetry.
* Both run client-side proof-of-work to make abuse expensive.
* Both work without any third-party network round-trip when self-hosted.
* Both are GDPR/CCPA-friendly by design.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): proof-of-work + instrumentation
* [All alternatives](../alternatives.md): full feature matrix
* [Open-source CAPTCHA options](../open-source-captcha.md): Cap, ALTCHA, mCAPTCHA and Anubis compared

---

---
url: /guide/alternatives/friendlycaptcha.md
description: >-
  Cap vs Friendly Captcha: a free, self-hosted, open-source proof-of-work
  CAPTCHA versus a paid SaaS. Compare privacy, pricing, and where your visitor
  data lives.
---

# Cap vs FriendlyCaptcha

FriendlyCaptcha was an early proof-of-work CAPTCHA, focused on EU privacy compliance. It's a hosted commercial service with a free tier for non-commercial use and paid tiers for everything else.

## Quick verdict

If you specifically need a paid, EU-hosted, vendor-supported product with an SLA and a sales contact, FriendlyCaptcha is a reasonable choice. If you want the same proof-of-work model without the bill or the request quota, Cap is a free, self-hosted, open-source alternative that you control end-to-end.

## Where FriendlyCaptcha makes sense

* You need a vendor with a contract, an SLA, and EU-based hosting handled by someone else.
* Your traffic is predictable and small enough to fit comfortably in a paid tier.
* You don't want to operate any infrastructure.

## Where Cap is the better choice

* **No quotas at any volume.** FriendlyCaptcha's Starter plan is €9/month for 1,000 requests/month, with higher tiers as you scale. Cap is free at any volume: no per-request fee, no domain limit.
* **Server is open-source.** FriendlyCaptcha's framework integrations are open-source but the server is proprietary. Cap is fully Apache-2.0, end to end.
* **Self-hosted.** Cap runs on your own infrastructure, on a $5 VPS, with no third-party round-trip.
* **Two verification layers.** Cap adds [instrumentation challenges](../instrumentation.md) on top of proof-of-work. FriendlyCaptcha is PoW only.
* **No "vendor risk."** Open-source, self-hosted, Apache 2.0. No surprise pricing changes, no surprise shutdowns.

## Where they're similar

* Both use proof-of-work as the primary mechanism.
* Both are GDPR/CCPA-friendly by design.
* Both have clean, accessible widget UX with no image puzzles.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): proof-of-work + instrumentation
* [All alternatives](../alternatives.md): full feature matrix
* [Best CAPTCHA alternatives in 2026](../best-captcha-alternatives.md): managed and self-hosted options ranked

---

---
url: /guide/alternatives/silentshield.md
description: >-
  Cap vs SilentShield: open-source, self-hosted proof-of-work CAPTCHA versus a
  hosted behavioral bot-detection service. Compare privacy, pricing and control.
---

# Cap vs SilentShield

**Short answer:** Cap is the better choice if you want an open-source (Apache 2.0), self-hosted CAPTCHA with no request quotas: it is free at any volume and imposes a computational cost that bots cannot act around. SilentShield is a closed-source hosted service with behavioral bot detection, free up to 500 requests per month and paid from €9/month for 5,000; it fits WordPress sites that want a managed, invisible plugin.

SilentShield is a hosted, invisible bot-protection service built by Forge12, a German company. It detects bots through behavioral analysis: an AI model evaluates mouse movement, keyboard input, scroll behavior, and interaction timing, so most users never see a challenge. It's popular in the WordPress ecosystem through its Contact Form 7 / WPForms / Elementor plugin.

Cap is a free, open-source, self-hosted CAPTCHA alternative that replaces visual puzzles with proof-of-work and [instrumentation challenges](../instrumentation.md). The two take fundamentally different approaches: SilentShield guesses whether you're human from how you behave, Cap makes automation expensive regardless of how well a bot imitates a human.

## Quick verdict

Cap is the better choice for teams that want an open-source, self-hosted CAPTCHA with no request quotas, deterministic difficulty, and full control over their users' data. SilentShield can suit WordPress sites that want a managed, zero-config, invisible product and whose traffic fits inside a paid tier. The core trade: SilentShield's verdicts are made by a closed model on someone else's servers; Cap's challenges run on yours, and you set the rules.

## Comparison

| | Cap | SilentShield |
| :-- | :-- | :-- |
| Open source | ✅ Apache 2.0, client and server | ❌ Closed-source service |
| Self-hosted | ✅ Docker (one container plus Valkey) | ❌ Hosted only (EU servers) |
| Free to use | ✅ At any volume | 🟨 Free up to 500 requests/month |
| Per-request fees | ✅ None | ❌ Tiered: €9/mo for 5,000, €29/mo for 25,000 requests |
| Primary mechanism | Proof-of-work + instrumentation | Behavioral analysis (mouse, keyboard, scroll, timing) |
| Deterministic difficulty | ✅ You set it, per site key | ❌ Model decides |
| Auditable detection logic | ✅ Read the code | ❌ Proprietary |
| Data leaves your infrastructure | ✅ Never | ❌ Interaction signals processed by SilentShield |
| Works without behavioral profiling | ✅ | ❌ Behavioral signals are the product |
| Widget customization | ✅ CSS variables for colors, size, shape | n/a (invisible by default) |
| reCAPTCHA-compatible siteverify | ✅ | ❌ |
| WordPress plugin | Community integrations | ✅ First-party (CF7, WPForms, Elementor, WooCommerce) |

## Where SilentShield makes sense

* You run a WordPress site and want a plug-and-play plugin with nothing to host.
* You want fully invisible protection and accept that a third-party model makes the pass/block decision.
* Your form volume fits comfortably inside a paid tier and the quota model doesn't bother you.
* EU-hosted processing (servers in Germany) satisfies your compliance requirements.

## Where Cap is the better choice

* **Open source, end to end.** Cap is Apache 2.0: widget, server, dashboard. You can audit exactly what runs in your users' browsers and on your servers. SilentShield's detection is a black box by design.
* **Self-hosted, no quotas.** Cap runs on your own infrastructure (a $5 VPS covers most sites) with no per-request fees and no monthly cap. SilentShield's free tier is 500 requests/month, which busier forms can exceed quickly.
* **The verdict is yours.** Behavioral systems produce a score, and when the model misfires there's no knob for you to turn. Cap's difficulty is deterministic and configured per site key: you decide how expensive a challenge is, and every user has a guaranteed path through.
* **Cost-based, not guess-based.** Behavioral analysis is a classification problem, and bots that replay recorded human input or use browser automation with humanized cursors attack the classifier directly. Cap's proof-of-work imposes a real computational cost that holds even against a bot that behaves perfectly, and [instrumentation challenges](../instrumentation.md) add a second, independent layer.
* **No third-party in the request path.** With Cap, nothing about your visitors (not their interaction patterns, not their IPs) is sent to a vendor. SilentShield is GDPR-oriented and EU-hosted, but the model still requires shipping interaction signals to their servers.
* **Drop-in migration path.** Cap's `/siteverify` endpoint is compatible with reCAPTCHA's API shape, so it slots into existing verification code with a URL swap.

## Where they're similar

* Both avoid image puzzles entirely: no traffic lights, no crosswalks, no distorted text.
* Both are designed with GDPR in mind and set no tracking cookies.
* Both ship a small client (SilentShield states under 10 KB, Cap's widget is ~20 KB).
* Both aim for a near-invisible experience for legitimate users.

## Privacy and data control

SilentShield markets a stronger privacy posture than reCAPTCHA's: EU servers, EU-only processing, and pseudonymised data, per Forge12's own descriptions. But its architecture still requires observing and processing how each visitor moves, types, and scrolls, on infrastructure you don't control. Cap sidesteps the question: there is no behavioral profile because the mechanism doesn't need one, and there is no vendor because you are the host. For a full breakdown of the regulations Cap is built around, see [Compliance](../compliance.md).

## FAQ

### Is Cap better than SilentShield?

For teams that want an open-source, self-hosted CAPTCHA with no per-request fees and full control over difficulty and data, Cap is the stronger choice. SilentShield fits teams that want a managed, invisible, behavioral-analysis service and are comfortable with a request quota and a third-party dependency.

### Is Cap open source?

Yes. Cap is fully open source under the Apache 2.0 license, including the widget, the server, and the standalone Docker deployment.

### Is SilentShield open source?

No. SilentShield is a closed-source hosted service. Its detection logic runs on SilentShield's servers and cannot be audited or self-hosted.

### Which is better for self-hosting?

Cap. It ships as a small Docker deployment you run on your own infrastructure with no third-party round-trip. SilentShield does not offer a self-hosted option.

### Which is better for privacy-focused teams?

Cap keeps everything on your servers: no cookies, no behavioral profiling, no data sent to any vendor. SilentShield is GDPR-oriented with EU servers, but its model depends on analyzing user interaction patterns on a third-party service.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): proof-of-work + instrumentation
* [All alternatives](../alternatives.md): full feature matrix
* [Best CAPTCHA alternatives in 2026](../best-captcha-alternatives.md): the wider field compared

---

---
url: /guide/alternatives/anubis.md
description: >-
  Cap vs Anubis: Anubis deters scrapers site-wide, Cap is a self-hosted,
  open-source CAPTCHA for forms and logins using proof-of-work. When to pick
  each one.
---

# Cap vs Anubis

Anubis is a proof-of-work scraper deterrent, popular in self-hosted communities for blocking AI training crawlers and aggressive scrapers at the edge. It and Cap share the proof-of-work core, but they're aimed at different problems.

## Quick verdict

Use **Anubis** when you want to gate an entire site or path against bots and scrapers at the reverse-proxy level, usually because crawlers are eating your bandwidth. Use **Cap** when you want to gate a specific *action* (a form submission, an API call, an account creation) and let normal browsing continue freely.

## Where Anubis makes sense

* You want to put a PoW wall in front of an entire site or sub-path.
* The threat model is mass scraping or bot-driven request floods at the edge.
* You're comfortable making every visitor solve a small challenge before any page loads.

## Where Cap is the better choice

* **Per-action protection, not per-pageview.** Cap protects forms, signups, contact pages, and API endpoints, exactly where abuse converts to cost. Visitors browse normally.
* **Difficulty is per-action.** Anubis's challenge has to be small enough not to hurt every page load, which limits how high you can crank it. Cap is configured per-action, so difficulty can be set higher on signup or login forms without hurting browsing.
* **Two verification layers.** Cap layers [instrumentation challenges](../instrumentation.md) on top of PoW, so even bots that bring GPU-acceleration to the proof-of-work step still have to fake a real browser environment.
* **Standalone server with a dashboard.** Cap ships analytics, multi-site-key management, and a reCAPTCHA-compatible siteverify endpoint out of the box.
* **Widget UX.** Cap is meant to be visible to humans on a form: there is a checkbox, progress indicator, and brand surface. Anubis is a transparent gate.

## They can coexist

If you're already running Anubis in front of a site for crawler protection, you can still use Cap on individual high-value forms and API endpoints inside that site. The two solve different problems and don't conflict.

## See also

* [Live demo](../demo.md): try Cap in your browser
* [How Cap detects bots](../effectiveness.md): proof-of-work + instrumentation
* [All alternatives](../alternatives.md): full feature matrix
* [Open-source CAPTCHA options](../open-source-captcha.md): Cap, ALTCHA, mCAPTCHA and Anubis compared

---

---
url: /guide/best-captcha-alternatives.md
description: >-
  The best CAPTCHA alternatives for 2026, ranked: Cap, Turnstile, ALTCHA,
  FriendlyCaptcha, hCaptcha, reCAPTCHA. Compare privacy, UX and cost to pick
  yours.
---

# Best CAPTCHA Alternatives for 2026

**Short answer:** the best CAPTCHA alternative depends on what you're optimizing for. **Cap**, an open-source, self-hosted proof-of-work CAPTCHA, is best for teams that want privacy-first protection with no per-request fees. **Cloudflare Turnstile** is best if you're already on Cloudflare and want zero hosting. **FriendlyCaptcha** is best if you want a paid, managed, EU-hosted proof-of-work service. **ALTCHA** is best if you want a minimal open-source proof-of-work library with nothing else attached.

Cap is a free, open-source CAPTCHA alternative that replaces visual puzzles with proof-of-work and [instrumentation challenges](./instrumentation.md), self-hosted as a single Docker container.

::: tip Full disclosure
This page lives in Cap's documentation, so we obviously have a favorite. The criteria are laid out below so you can weigh them yourself, and where a competitor is the better fit, we say so.
:::

## Comparison at a glance

| Product | Best for | Open source | Self-hosted | Privacy-first | Free at scale | UX | Bot resistance |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| **Cap** | Full control, privacy, $0 | ✅ Apache 2.0 | ✅ | ✅ | ✅ | Checkbox, no puzzles | PoW + instrumentation |
| Cloudflare Turnstile | Cloudflare-native stacks | ❌ | ❌ | 🟨 fingerprinting | ✅ | Invisible, but error-prone | Network signals |
| ALTCHA | Minimal OSS library | ✅ MIT (widget) | ✅ | ✅ | ✅ | Checkbox, no puzzles | PoW only (OSS tier) |
| FriendlyCaptcha | Managed EU PoW service | 🟨 clients only | ❌ | ✅ | ❌ quotas | Invisible/checkbox | PoW only |
| hCaptcha | Enterprise, puzzle-tolerant | ❌ | ❌ | 🟨 | 🟨 | Image puzzles | High, at UX cost |
| reCAPTCHA | Google-integrated stacks | ❌ | ❌ | ❌ | 🟨 | Puzzles / risk score | Mixed |
| SilentShield | WordPress, managed invisible | ❌ | ❌ | 🟨 behavioral | ❌ 500 req/mo free | Invisible | Behavioral model |

The full 12-criteria matrix (error rates, GDPR, customization, RSW support and more) is on the [feature comparison](./alternatives.md) page.

## The alternatives, ranked

### 1. Cap

Cap is an open-source (Apache 2.0), self-hosted CAPTCHA that makes automation expensive instead of guessing who's human. Users click one checkbox; a proof-of-work challenge runs silently in their browser while [instrumentation challenges](./instrumentation.md) verify the environment is a real browser.

* **Best for:** teams that want full control, real privacy, and no bill at any traffic volume.
* **Key strengths:** two independent verification layers (PoW + instrumentation), ~20 KB widget, deterministic difficulty you control per site key, reCAPTCHA-compatible `/siteverify` API, dashboard with multi-site-key management, works in Brave, Librewolf, and Tor Browser.
* **Tradeoffs:** you host it (one Docker container plus Valkey; a $5 VPS covers most sites). If you refuse to run any backend service, a managed option fits better.
* **Privacy:** no cookies, no fingerprinting, no third-party calls. Data never leaves your servers. See [Compliance](./compliance.md).

[Quickstart →](./index.md)

### 2. Cloudflare Turnstile

Turnstile is Cloudflare's free CAPTCHA replacement, running invisible challenges that lean on Cloudflare's network signals and browser fingerprinting.

* **Best for:** sites already routing traffic through Cloudflare that want zero hosting.
* **Key strengths:** free, fully managed, invisible for most users, easy integration.
* **Tradeoffs:** closed source, no self-hosting, and no override when Cloudflare's algorithm flags a user as suspicious, which is widely reported for privacy browsers and VPN users. The verdict is theirs, not yours.
* **Privacy:** better than reCAPTCHA, but the client talks to `challenges.cloudflare.com` on every load and relies on fingerprinting signals.

[Full comparison: Cap vs Turnstile →](./alternatives/turnstile.md)

### 3. ALTCHA

ALTCHA is the closest open-source project to Cap in spirit: proof-of-work, no fingerprinting, no third party.

* **Best for:** developers who want a minimal, library-style PoW widget with no separate service.
* **Key strengths:** open source (MIT widget), self-hostable, GDPR-friendly, well documented.
* **Tradeoffs:** PoW only in the open-source tier (the ML-based second layer requires the paid Sentinel product), ~34 KB widget, no standalone server or dashboard out of the box.

[Full comparison: Cap vs ALTCHA →](./alternatives/altcha.md)

### 4. FriendlyCaptcha

An early proof-of-work CAPTCHA, now a hosted commercial service focused on EU privacy compliance.

* **Best for:** teams that want a vendor with a contract, SLA, and EU hosting, and whose traffic fits a paid tier.
* **Key strengths:** clean PoW model, GDPR-friendly, accessible widget, no puzzles.
* **Tradeoffs:** the server is proprietary and there's no self-hosting. Pricing starts at €9/month for 1,000 requests/month and scales with volume.

[Full comparison: Cap vs FriendlyCaptcha →](./alternatives/friendlycaptcha.md)

### 5. SilentShield

A hosted, invisible bot-protection service by German company Forge12, distributed mainly as a WordPress plugin. Detection is behavioral: per Forge12, an AI model scores interaction patterns such as mouse, keyboard, scroll, and timing.

* **Best for:** WordPress sites that want plug-and-play invisible protection and accept a request quota.
* **Key strengths:** invisible for most users, EU servers, first-party plugins for CF7, WPForms, Elementor, and WooCommerce, and a small client (stated as under 10 KB).
* **Tradeoffs:** closed source, no self-hosting, free tier capped at 500 requests/month (paid tiers from €9/month for 5,000). Behavioral classification is probabilistic, and bots that imitate human input target the classifier directly; unlike proof-of-work, this approach does not impose a computational cost floor on attackers.

[Full comparison: Cap vs SilentShield →](./alternatives/silentshield.md)

### 6. hCaptcha

reCAPTCHA's main commercial rival, built on image-labeling puzzles.

* **Best for:** enterprises that need aggressive protection and accept the UX cost.
* **Key strengths:** strong bot resistance, enterprise features, compliance options.
* **Tradeoffs:** users hate puzzles, and drop-off on hCaptcha challenges can reach 5-15% depending on difficulty. The free tier serves puzzles aggressively.

[Full comparison: Cap vs hCaptcha →](./alternatives/hcaptcha.md)

### 7. reCAPTCHA

Google's incumbent, in v2 ("I'm not a robot") and v3 (invisible, score-based) flavors.

* **Best for:** stacks already deep in Google's ecosystem.
* **Key strengths:** ubiquitous, familiar, free for moderate volumes.
* **Tradeoffs:** sends user data to Google, 500 KB+ client, v2's puzzles are increasingly easy for AI and hard for humans, v3 silently penalizes VPN and privacy-browser users, and Enterprise is metered per assessment.

[Full comparison: Cap vs reCAPTCHA →](./alternatives/recaptcha.md) · [Migration guide →](./alternatives/migrate-from-recaptcha.md)

### Also worth knowing

* **Anubis**: a proof-of-work scraper deterrent for gating entire sites at the proxy level rather than a form CAPTCHA. [Cap vs Anubis →](./alternatives/anubis.md)
* **mCAPTCHA**: an open-source (AGPL-3.0 core) proof-of-work CAPTCHA that pioneered variable-difficulty PoW and ships its own standalone server. It remains pre-1.0 with a slow release cadence, its widget bundle is larger than Cap's or ALTCHA's, and the AGPL license complicates commercial embedding. [Full breakdown →](./open-source-captcha.md)

More options (MTCaptcha, GeeTest, Arkose Labs) are covered on the [feature comparison](./alternatives.md) page.

## How do you choose a CAPTCHA alternative?

1. **Do you refuse to host anything?** Turnstile (free, Cloudflare verdicts) or FriendlyCaptcha (paid, EU, PoW).
2. **Do you want open source and control?** Cap, either as a full standalone server with a dashboard or as a [minimal server library](./capjs-core.md); ALTCHA is another solid library-only option.
3. **Is conversion your top metric?** Avoid anything with image puzzles. See [CAPTCHA and conversion rate](./captcha-conversion-rate.md).
4. **Mostly mobile traffic?** See [bot protection for mobile forms](./mobile-form-bot-protection.md).
5. **WordPress with low traffic?** SilentShield's plugin is convenient; Cap works there too via community integrations without the quota.

## FAQ

### What is the best CAPTCHA alternative?

It depends on your priorities. Cap is the best fit for open-source, self-hosted, privacy-first protection with no fees. Turnstile fits Cloudflare-native stacks, FriendlyCaptcha fits teams that want a managed EU PoW vendor, and ALTCHA fits minimalists.

### What is the best open-source CAPTCHA alternative?

Cap and ALTCHA. Cap adds a standalone server, dashboard, instrumentation challenges, and a reCAPTCHA-compatible API on top of proof-of-work; ALTCHA stays a lean library. See [open-source CAPTCHA options](./open-source-captcha.md).

### What is the best self-hosted CAPTCHA?

Cap. A small Docker deployment, a web dashboard, multi-site-key support, and no third-party round-trip. Nothing about your visitors leaves your servers. [Quickstart →](./index.md)

### Which CAPTCHA alternative is best for privacy?

Self-hosted proof-of-work options, because they need no fingerprinting or behavioral profiling. Cap sets no cookies and sends nothing to any vendor, and it doesn't penalize Brave, Librewolf, Tor, or VPN users.

### Which CAPTCHA alternative has the best user experience?

Anything without visual puzzles. Cap shows a single checkbox with a live progress indicator; Turnstile and SilentShield are invisible for users their models classify as human; hCaptcha and reCAPTCHA v2 still drop users into image challenges.

### What is the best invisible CAPTCHA?

Turnstile and SilentShield are invisible by default but rely on fingerprinting or behavioral scoring, so misclassified users get blocked with no recourse. Cap's [floating](./floating.md) and [programmatic](./programmatic.md) modes are invisible until submit while staying deterministic: every real user has a guaranteed path through.

### Is Cap a good alternative to reCAPTCHA?

Yes. The `/siteverify` API is compatible with reCAPTCHA's shape, so server-side migration is mostly a URL swap, and you can run both side by side during cut-over. Unlike reCAPTCHA, Cap is open source, self-hosted, and never shows image puzzles. See the [migration guide](./alternatives/migrate-from-recaptcha.md).

## See also

* [Feature comparison](./alternatives.md): the full 12-criteria matrix
* [CAPTCHA and conversion rate](./captcha-conversion-rate.md): the UX cost of puzzles
* [Open-source CAPTCHA options](./open-source-captcha.md): Cap, ALTCHA, mCAPTCHA, Anubis
* [Live demo](./demo.md): try Cap in your browser

---

---
url: /guide/captcha-conversion-rate.md
description: >-
  How CAPTCHA affects conversion rates on signup, login and checkout forms, and
  how low-friction alternatives like Cap protect forms without losing users.
---

# CAPTCHA Conversion Rate: How Puzzles Hurt Signups

**Short answer:** yes, CAPTCHA reduces conversion rates when it adds visible friction. Visual puzzles take 10 to 26 seconds to solve, fail on retries, and are served most aggressively to mobile, VPN, and privacy-browser users; drop-off on hCaptcha challenge screens reaches 5-15% depending on difficulty. You can keep the bot protection and drop the interrogation. Cap is a free, open-source, self-hosted CAPTCHA alternative that runs proof-of-work silently behind a single checkbox, so real users are never judged by a risk score while automation stays expensive.

## How much does CAPTCHA reduce conversion rates?

Every form has a funnel, and a CAPTCHA sits directly in front of the submit button. Three failure modes cost you users:

1. **Time and effort.** Image puzzles ("select all traffic lights") take seconds to minutes, often across multiple rounds. Some users fail, retry, and give up. Drop-off on hCaptcha challenges can reach **5-15%** depending on difficulty.
2. **False positives.** Score-based systems like reCAPTCHA v3 and fingerprint-based systems like Turnstile silently penalize users on VPNs, Brave, Librewolf, Tor Browser, or hardened Firefox. Those users get harder puzzles, endless loops, or flat rejections, with no path through and no way for you to override the vendor's verdict.
3. **Accessibility barriers.** Visual puzzles are hostile to low-vision users, and audio fallbacks are both frustrating and, ironically, easier for AI solvers than for humans. Failed accessibility is lost conversion too.

The cruel part: the puzzles are increasingly *easier for bots than for humans*. Modern vision models solve traffic-light grids reliably, while your real users squint at blurry crosswalks.

## What the research shows

* A Stanford study of over 1,100 participants (Bursztein et al.) found humans take about 9.8 seconds on average to solve a text CAPTCHA and 28.4 seconds for audio CAPTCHAs, with a large share of audio attempts abandoned.
* A 2023 UC Irvine study (Searles et al.) measured 15 to 26 seconds for image-based challenges, with 71 to 85 percent human accuracy, while bots solved the same challenges faster and more accurately.
* Industry reports put drop-off on hCaptcha visual challenges at 5 to 15 percent depending on difficulty.

The pattern is consistent: visible puzzles cost measurable conversion, the friction sits directly before the submit button, and it lands on every visitor, human or not.

## Where users abandon CAPTCHA challenges

* **The first puzzle screen.** The moment a grid of images appears, a fraction of users leaves immediately, especially when the form was low-commitment (newsletter, contact form).
* **The retry loop.** "Please try again" after a genuine attempt is the strongest abandonment trigger. Privacy-browser users see this loop far more often.
* **Mobile.** Small tap targets, image grids that require zooming, and puzzles interrupting autofill flows. See [bot protection for mobile forms](./mobile-form-bot-protection.md).
* **Checkout.** Users with payment intent are valuable and impatient. Every second of challenge time here is directly measurable revenue.

## Why low-friction CAPTCHA performs better

An ideal CAPTCHA for conversion has two properties:

* **No risk-score false positives.** Humans are not classified at all: any browser that can run the challenge passes, regardless of network, extensions, or privacy settings.
* **Minimal perceived effort.** One click or nothing at all, with clear progress feedback if there's any wait.

Behavioral and fingerprint-based "invisible" systems get the second property but sacrifice the first: their models must sometimes guess wrong, and the wrong guesses cluster on exactly the users a vendor's training data underrepresents. Proof-of-work gets both: the challenge is solved by the visitor's *device*, not judged against the visitor's *identity*, so there is nothing to misclassify.

## How Cap protects conversion

Cap replaces puzzles with two invisible layers:

* **Proof-of-work**: the browser performs a short computation. Cheap for one legitimate visitor, expensive for a bot doing it a million times. The user sees a checkbox tick and a progress percentage, nothing else. [How it works →](./workings.md)
* **Instrumentation challenges**: dynamic checks that the environment is a real browser, inspired by the custom challenges used by Twitter and YouTube. [Details →](./instrumentation.md)

For conversion-sensitive flows this means:

* No image puzzles, ever. There is no "hard mode" to fall into.
* No risk scores, so no silent penalties for VPNs or privacy browsers.
* You control difficulty per site key: crank it up on signup, keep it feather-light on checkout.
* [Floating](./floating.md) and [programmatic](./programmatic.md) modes make it fully invisible until submit.
* The widget is ~20 KB, so it doesn't slow the page it's supposed to protect. See the [benchmark](./benchmark.md).

Because Cap's proof-of-work is deterministic, no human is ever misclassified by a risk score: any browser that can run the challenge passes. Abandonment is limited to users unwilling to wait the few seconds the solve takes, and the widget's progress indicator keeps that wait legible.

## By use case

| Flow | What matters | Recommendation |
| :-- | :-- | :-- |
| Signup forms | Zero false positives; this is your growth funnel | Cap with default difficulty; instrumentation on |
| Login forms | Throttle credential stuffing without punishing real users | Cap with higher difficulty, or trigger only after failed attempts |
| Checkout | Every second is revenue | Cap in [floating mode](./floating.md), low difficulty |
| Contact forms | Spam volume, low user commitment | Cap default; even a visible checkbox is fine here |
| Mobile forms | No puzzles, small bundle, autofill-friendly | See the [mobile guide](./mobile-form-bot-protection.md) |

## How the alternatives compare on conversion

* **reCAPTCHA v2**: the archetypal conversion killer; puzzle loops for anyone Google distrusts. [Cap vs reCAPTCHA →](./alternatives/recaptcha.md)
* **reCAPTCHA v3**: invisible until it isn't; low scores silently gate users you never see. No override.
* **hCaptcha**: strong protection, heavy puzzle tax, and the free tier serves puzzles aggressively. [Cap vs hCaptcha →](./alternatives/hcaptcha.md)
* **Turnstile**: invisible and free, but known for a high error rate on privacy browsers, and you can't override its verdicts. [Cap vs Turnstile →](./alternatives/turnstile.md)
* **FriendlyCaptcha**: good low-friction PoW model, but hosted, quota-priced, and PoW-only. [Cap vs FriendlyCaptcha →](./alternatives/friendlycaptcha.md)
* **SilentShield**: invisible behavioral scoring, so the conversion experience is good *when the model is right*; misclassifications are out of your hands, and the free tier is capped at 500 requests/month, with paid tiers from €9/month for 5,000 requests. [Cap vs SilentShield →](./alternatives/silentshield.md)

## FAQ

### Does CAPTCHA reduce conversion rates?

It can, and puzzle-based CAPTCHA reliably does. The three drivers are challenge time, retry loops, and false positives on privacy-conscious users. Low-friction, deterministic mechanisms minimize all three.

### What CAPTCHA is best for conversions?

One with no puzzles and no misclassification. Cap never judges the user with a risk score: it runs proof-of-work silently and keeps the interaction to a single checkbox (or nothing, in floating mode).

### Is invisible CAPTCHA better for conversion rates?

Only when its error rate is low. An invisible system that funnels a slice of users into hard puzzles or blocks can be worse than a visible checkbox that always passes humans.

### How does Cap avoid annoying users?

No image selection, no text distortion, no audio challenges. A checkbox, a progress bar, a few seconds. And because it's self-hosted, there's no third-party script bloating your page.

### What is the best CAPTCHA for signup forms?

A deterministic, puzzle-free one. Cap was built for this: proof-of-work plus instrumentation, ~20 KB widget, difficulty you control, and a reCAPTCHA-compatible API so you can migrate without rewriting your backend.

## See also

* [Best CAPTCHA alternatives in 2026](./best-captcha-alternatives.md): the full field ranked
* [Bot protection for mobile forms](./mobile-form-bot-protection.md): the mobile-specific version of this problem
* [Effectiveness](./effectiveness.md): why making bots pay beats guessing who's human
* [Live demo](./demo.md): feel the UX yourself

---

---
url: /guide/open-source-captcha.md
description: >-
  The best open-source, self-hosted CAPTCHA options for developers compared:
  Cap, ALTCHA, mCAPTCHA, and Anubis, with licensing, architecture, and how to
  choose.
---

# Best Open-Source CAPTCHA Options in 2026

**Short answer:** Cap is a free, open-source, self-hosted CAPTCHA alternative licensed under Apache 2.0 that uses proof-of-work and [instrumentation challenges](./instrumentation.md) instead of visual puzzles. The other serious open-source options are **ALTCHA** (minimal PoW library), **mCAPTCHA** (PoW, pre-1.0 and slow-moving), and **Anubis** (PoW scraper wall for whole sites rather than forms).

## What makes a CAPTCHA open source?

A public widget repo on its own doesn't qualify. For bot protection, "open source" only means something when you can audit and run the parts that make decisions:

* **Client and server code published** under an OSI license, so the challenge logic isn't a black box.
* **Self-hostable verification**, so passing or failing a user never depends on a vendor's API being up, honest, or affordable.
* **No hidden phone-home**, which you can verify because you can read the code.

Several commercial CAPTCHAs open-source their client integrations while keeping the server proprietary (FriendlyCaptcha, for example). That's source-available convenience, not an open-source CAPTCHA: the decision engine is still a black box you rent.

## Why self-host CAPTCHA?

* **Privacy you can prove.** Visitor data never reaches a vendor, which makes GDPR/CCPA answers simple. See [Compliance](./compliance.md).
* **No quotas or per-request fees.** Traffic spikes and bot floods don't turn into invoices.
* **No vendor risk.** No surprise pricing changes, no deprecations, no acquisition rugs.
* **Control.** You set challenge difficulty per site key instead of trusting a remote model's verdict on your users.
* **Availability.** Your forms don't break when a third-party challenge endpoint has an outage.

## The options

### Cap

Cap is a full open-source CAPTCHA stack under Apache 2.0: a ~20 KB web-component widget plus [Cap Standalone](./standalone/index.md), a small Docker deployment (one container plus Valkey) exposing a REST API, a dashboard with multi-site-key management, and a `/siteverify` endpoint compatible with reCAPTCHA's API shape.

Protection comes from two independent layers: GPU-resistant [HashWX proof of work](./hashwx.md) and dynamic [instrumentation challenges](./instrumentation.md) that verify the environment is a real browser. Defeating one layer doesn't defeat the other.

If you'd rather embed than deploy, [capjs-core](./capjs-core.md) is Cap's stateless server library: it generates and verifies challenges inside your own service and runs on Cloudflare Workers, Lambda, and other edge environments with no persistent storage.

* **License:** Apache 2.0, client and server
* **Mechanism:** proof-of-work + instrumentation
* **Deployment:** Docker container + CDN or self-hosted widget
* **Best for:** teams that want a turn-key, self-hosted CAPTCHA service with real UX

### ALTCHA

ALTCHA is a minimal, well-maintained proof-of-work widget (MIT) you wire into your own backend. No dashboard, no standalone server in the open-source tier; the ML-based second layer is part of the paid Sentinel product.

* **License:** MIT (widget)
* **Mechanism:** proof-of-work
* **Best for:** developers who want a small library and are happy to build the server side themselves

[Full comparison: Cap vs ALTCHA →](./alternatives/altcha.md)

### mCAPTCHA

mCAPTCHA pioneered the same variable-difficulty PoW idea. It's fully open source (the core is AGPL-3.0; client libraries use permissive licenses), but it is still pre-1.0 with a slow release cadence, and its widget bundle is larger than Cap's or ALTCHA's. Fine to study, but weigh the maturity before building on it.

### Anubis

Anubis is an open-source proof-of-work *scraper wall*: it gates an entire site or path at the reverse-proxy level, mainly against AI crawlers. It's not a form CAPTCHA and doesn't ship a standalone verification server, but it pairs well with one. You can run Anubis in front of a site and Cap on the high-value forms inside it.

[Full comparison: Cap vs Anubis →](./alternatives/anubis.md)

## Side by side

| | Cap | ALTCHA | mCAPTCHA | Anubis |
| :-- | :-- | :-- | :-- | :-- |
| License | Apache 2.0 | MIT (widget) | AGPL | MIT |
| Actively maintained | ✅ | ✅ | 🟨 pre-1.0, slow releases | ✅ |
| Mechanism | PoW + instrumentation | PoW | PoW | PoW |
| Scope | Per-action (forms, APIs) | Per-action | Per-action | Whole-site gate |
| Standalone server + dashboard | ✅ | ❌ | ✅ | ❌ |
| reCAPTCHA-compatible siteverify | ✅ | ❌ | ❌ | ❌ |
| Widget size | ~20 KB | ~34 KB | larger | n/a (transparent) |
| GPU-resistant PoW option | ✅ [HashWX](./hashwx.md) | ❌ | ❌ | ❌ |

## How to choose

* **Want a service you deploy once and manage in a dashboard?** Cap. [Quickstart →](./index.md)
* **Want the smallest possible dependency and you'll own the backend glue?** Cap's [capjs-core](./capjs-core.md) library, or ALTCHA.
* **Fighting scrapers across a whole site, not form spam?** Anubis, optionally with Cap on the forms.
* **Migrating off reCAPTCHA or hCaptcha?** Cap's compatible siteverify makes it a URL swap. [Migration guide →](./alternatives/migrate-from-recaptcha.md)

## FAQ

### What is the best open-source CAPTCHA?

Cap, if you want a complete stack: two verification layers, dashboard, compatible siteverify API. ALTCHA, if you want a minimal library.

### Can I self-host CAPTCHA?

Yes, and it's easier than it sounds. Cap runs as one Docker container plus Valkey, fits on a $5 VPS, and takes about five minutes to set up.

### Is Cap free?

Completely. Apache 2.0, no quotas, no paid tier, at any volume.

### Is Cap better than ALTCHA?

Cap ships more (instrumentation layer, standalone server, dashboard, progress UX, smaller widget); ALTCHA ships less on purpose. Pick by how much you want to build yourself.

### Does open-source CAPTCHA protect privacy?

It makes privacy auditable instead of promised. Self-hosted PoW needs no fingerprinting, no behavioral profiling, and no third-party calls, and you can read the code to confirm it.

## See also

* [Best CAPTCHA alternatives in 2026](./best-captcha-alternatives.md): including the closed-source field
* [Feature comparison](./alternatives.md): the full matrix
* [How does Cap work?](./workings.md): the architecture in detail
* [Live demo](./demo.md): try the widget

---

---
url: /guide/mobile-form-bot-protection.md
description: >-
  How to stop bots on mobile forms without image puzzles: what a mobile-friendly
  CAPTCHA needs and how Cap's one-tap proof-of-work fits. Try the live demo.
---

# CAPTCHA for Mobile Forms: Bot Protection Without the Puzzles

**Short answer:** the best bot protection for mobile forms avoids image puzzles entirely, ships a small bundle, works in webviews and privacy browsers, and never punishes users for weak fingerprint signals. Cap is a free, open-source, self-hosted CAPTCHA alternative built around exactly this: a one-tap checkbox backed by proof-of-work and [instrumentation challenges](./instrumentation.md) instead of puzzles or profiling.

## Why is CAPTCHA worse on mobile?

Mobile is where CAPTCHAs do the most conversion damage:

* **Image grids don't fit.** "Select all traffic lights" on a 6-inch screen means squinting, zooming, and mis-taps. Retry loops that are annoying on desktop are rage-inducing on mobile.
* **Keyboards and autofill get interrupted.** A challenge that appears mid-form dismisses the keyboard, breaks autofill flows, and loses the user's place.
* **Weaker signals for "invisible" systems.** Fingerprint and behavioral systems lean on mouse movement and stable network identity. Mobile has no mouse, heavy carrier-grade NAT (thousands of users behind one IP), and aggressive tracking prevention in Safari. Less signal means more wrong guesses, and wrong guesses become puzzles or blocks.
* **Webviews.** A huge share of mobile traffic comes from in-app browsers (Instagram, TikTok, Gmail), which look "suspicious" to fingerprint-based systems.
* **Bandwidth and battery.** A 500 KB+ CAPTCHA script on a mid-range phone over cellular is a real cost before the user has typed anything.

## What mobile-friendly bot protection needs

1. **No visual puzzles**, under any fallback condition. If the system *can* serve a grid, mobile users will eventually get one.
2. **Deterministic pass for humans.** No risk scores that degrade on NAT'd carrier IPs or webviews.
3. **Small bundle.** The protection shouldn't cost more than the form.
4. **Touch-first UX.** One tap at most, clear progress feedback, no keyboard interruption.
5. **Tunable cost.** Solve time should be a knob you control, so low-end devices aren't stuck waiting.

## How Cap works on mobile forms

* **One tap, then progress.** The user taps a checkbox; a progress percentage fills while the proof-of-work runs in the browser. No images, no typing, no keyboard dismissal. In [floating](./floating.md) or [programmatic](./programmatic.md) mode there's nothing visible at all until submit.
* **~20 KB widget.** A single web component, no framework dependency, cheap over cellular. See the [benchmark](./benchmark.md).
* **No fingerprint penalty.** Cap doesn't care that the visitor is behind carrier NAT, inside an Instagram webview, or on iOS Safari with tracking prevention. The proof-of-work is the same computation for everyone.
* **Difficulty is yours to tune.** Set it per site key on the [standalone server](./standalone/options.md): lighter for consumer checkout traffic on mid-range Androids, heavier for abuse-prone signup endpoints.
* **Instrumentation still applies.** [Instrumentation challenges](./instrumentation.md) verify a real browser environment, catching headless automation that PoW alone wouldn't, without profiling the human.

One honest tradeoff: proof-of-work costs CPU time, and low-end phones solve slower than desktops. Cap mitigates this with configurable difficulty and visible progress feedback, and the work happens once per form, not per pageview.

## How the field compares on mobile

* **reCAPTCHA v2 / hCaptcha:** image grids are the worst-case mobile experience, and both fall back to them. reCAPTCHA's client also weighs 500 KB+. [Cap vs reCAPTCHA →](./alternatives/recaptcha.md) · [Cap vs hCaptcha →](./alternatives/hcaptcha.md)
* **reCAPTCHA v3:** invisible, but score-based, and mobile's weak signals (NAT, webviews) drag scores down with no recourse.
* **Turnstile:** invisible and light, but fingerprint-driven; privacy features in mobile Safari and webviews are known sources of errors, and you can't override its verdict. [Cap vs Turnstile →](./alternatives/turnstile.md)
* **FriendlyCaptcha:** PoW like Cap, so mechanically fine on mobile, but hosted, quota-priced, and PoW-only. [Cap vs FriendlyCaptcha →](./alternatives/friendlycaptcha.md)
* **SilentShield:** behavioral analysis leans on mouse, keyboard, and scroll patterns, signals that are thinner and differently-shaped on touch devices; classification quality on mobile is inherently harder to verify, and it's a closed, quota-priced service. [Cap vs SilentShield →](./alternatives/silentshield.md)

## Implementation notes

* Put the widget inside your `<form>` and Cap injects the `cap-token` field automatically; no JavaScript needed. [Quickstart →](./index.md)
* For SPAs and app webviews, use the `solve` event or [programmatic mode](./programmatic.md) to keep full control of the flow.
* Test on a real mid-range Android over cellular, not just a flagship on Wi-Fi, and tune difficulty until solve time feels instant for your audience.
* Protecting a native app's API rather than a web form? Cap's [standalone server](./standalone/api.md) verifies tokens from any client that can run the challenge in a webview.

## FAQ

### What is the best CAPTCHA for mobile forms?

One that can never show a puzzle and never misclassifies. Cap's checkbox-plus-proof-of-work model is deterministic, ~20 KB, and touch-first.

### How do I stop spam on mobile forms?

Impose cost instead of asking questions. Proof-of-work makes each submission computationally expensive for bots at scale while staying a single tap for humans.

### Is invisible CAPTCHA better on mobile?

Only if its error rate holds up, and mobile is exactly where fingerprint and behavioral signals are weakest. Deterministic mechanisms don't have that failure mode.

### Does Cap work on mobile?

Yes: mobile Safari, Chrome, Firefox, and in-app webviews. Difficulty is tunable so solve time stays short on slower devices.

### What CAPTCHA has the least user friction?

Puzzle-free options: Cap, Turnstile, FriendlyCaptcha, ALTCHA, SilentShield. Cap is the open-source, self-hosted one where low friction comes from the mechanism's design rather than from a classifier's verdict.

## See also

* [CAPTCHA and conversion rate](./captcha-conversion-rate.md): the desktop-and-mobile funnel math
* [Best CAPTCHA alternatives in 2026](./best-captcha-alternatives.md): the full field
* [Live demo](./demo.md): try it on your phone
* [Effectiveness](./effectiveness.md): why cost beats classification

---

---
url: /guide/standalone.md
description: >-
  Cap Standalone is the easiest way to self-host the open-source CAPTCHA
  backend: Docker, instrumentation, a reCAPTCHA-compatible API, and a web
  dashboard.
---

# Cap Standalone

Cap Standalone is the recommended way to self-host Cap's backend. It runs on Bun and keeps idle memory usage around 50 MB. It ships with built-in support for instrumentation challenges, which significantly raise the bar for bots, a siteverify API compatible with reCAPTCHA, and a web dashboard for managing multiple site keys.

We recommend using [Docker](https://docs.docker.com/get-docker/) to run Cap Standalone.

## Installation

Create a `docker-compose.yml` file:

```yaml
services:
  cap:
    image: tiago2/cap:latest
    container_name: cap
    ports:
      - "3000:3000"
    environment:
      ADMIN_KEY: your_secret_password
      REDIS_URL: redis://valkey:6379
    depends_on:
      valkey:
        condition: service_healthy
    restart: unless-stopped

  valkey:
    image: valkey/valkey:9-alpine
    container_name: cap-valkey
    volumes:
      - valkey-data:/data
    command: valkey-server --save 60 1 --loglevel warning --maxmemory-policy noeviction
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  valkey-data:
```

::: tip Tips

* `ADMIN_KEY` is your dashboard's login. We recommend making it at least 32 characters
* Change `3000:3000` if that port is already in use on your host.
* If the dashboard is unreachable, try adding `network_mode: "host"` under the `cap` service.
  :::

Start the container:

```bash
docker compose up -d
```

Open `http://localhost:3000` (or your server's IP/domain on port 3000) to access the dashboard. Log in with your admin key, create a site key, and note down both the **site key** and its **secret key**, you'll need both.

Instrumentation challenges are enabled by default when creating new site keys. We recommend keeping them on, as they significantly raise the bar for bots. You can also enable headless browser detection for additional protection.

Your Cap Standalone instance must be publicly reachable from the internet so the widget can communicate with it. If you're using a reverse proxy, review the [options guide](/guide/standalone/options.md) to configure rate-limiting correctly.

## Usage

### Client-side

Point the widget at your instance by setting the `data-cap-api-endpoint` attribute:

```
https://<instance_url>/<site_key>/
```

* `<instance_url>` — the public URL of your Cap Standalone instance
* `<site_key>` — the site key from your dashboard

Example:

```html
<cap-widget data-cap-api-endpoint="https://cap.example.com/d9256640cb53/"></cap-widget>
```

We recommend reading our [widget documentation](../widget.md) for more details and example snippets for multiple frameworks.

### Server-side

Once a user completes the CAPTCHA, your backend must verify the token before trusting it. Send a `POST` request to your instance's `/siteverify` endpoint with the following JSON body:

```bash
curl "https://<instance_url>/<site_key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'
```

Where `<key_secret>` is the secret key from your dashboard (**not** the dashboard admin key), and `<captcha_token>` is the challenge token generated by the widget.

A successful verification returns:

```json
{ "success": true }
```

---

---
url: /guide/standalone/api.md
description: >-
  REST API reference for Cap Standalone: create and manage site keys and
  sessions for the self-hosted, open-source CAPTCHA using bearer-authenticated
  requests.
---

# API

Standalone mode offers a simple API for creating, viewing, and managing keys and sessions. First, log in to your Cap Standalone dashboard and get an API key from **Settings** → **API Keys**. Give it a name and tap "Create".

Once your key is created, save it somewhere safe, as you won't be able to see it again.

Now, you can use this key to make API requests to your Standalone server. For each request you make, you'll need to include the `Authorization` header with your API key, like this:

```http
Authorization: Bot YOUR_API_KEY
```

You can see a list of all available API endpoints and their required bodies by going to `http://localhost:3000/swagger`

## Scoped API keys

By default, an API key can read and change every site key on the instance. When creating a key from **Settings** → **API keys**, you can restrict it:

* **Site key access**: pick specific site keys. The key can then only call the `/server/keys/:siteKey/...` endpoints for those keys, and `GET /server/keys` only lists them. Every other endpoint, including the settings endpoints, returns `403`.
* **Read-only**: only `GET` requests are allowed. Creating, updating, rotating or deleting anything returns `403`.

Both restrictions can be combined. A read-only key scoped to a single site key is safe to hand to the owner of that site, for example to pull their own stats into their own dashboard.

The same options are available when creating a key through the API:

```http
POST /server/settings/apikeys
Content-Type: application/json

{ "name": "acme stats", "siteKeys": ["<site key>"], "readonly": true }
```

Keys created before this option existed keep full access.

## Share links

A share link is a public, read-only stats page for a single site key. Open the key in the dashboard, go to **Configuration** → **Share links** and create one. Anyone who has the link sees the challenge and verification counts, the activity chart and the location, network, platform and OS breakdowns for that key. They can't see the key's configuration, secret or block rules, and they can't change anything.

Links can be given a label and an expiry date, and can be revoked at any time from the same section. The token lives in the URL fragment (after the `#`), so the page request itself never carries it and it doesn't leak through referer headers. The two API calls the page makes do include the token in their path, so a reverse proxy that logs request paths will see it.

If you want to embed the numbers somewhere else instead of using the page, the link's token works against two unauthenticated, rate-limited endpoints:

```http
GET /share/:token?chartDuration=last7days
GET /share/:token/geo-stats
```

`chartDuration` accepts `today`, `yesterday`, `last7days`, `last28days`, `last91days` or `alltime`.

When creating a link through `POST /server/keys/:siteKey/shares`, `expiresIn` is in seconds. Omitting it or passing `0` creates a link that never expires.

---

---
url: /guide/standalone/options.md
description: >-
  Configuration options and environment variables for Cap Standalone, the
  self-hosted open-source CAPTCHA: CORS, asset server, widget and WASM versions,
  and more.
---

# Options

## CORS

You can change the default CORS settings for redeeming and generating challenges by setting the `CORS_ORIGIN` environment variable when running the server. This defaults to `*`, which allows all origins. You can add multiple origins by separating them with commas, like `domain1.tld,domain2.tld,...`.

## Asset server

The asset server is disabled by default. You can enable it by setting the `ENABLE_ASSETS_SERVER` environment variable to `true`. This will serve the assets from the `/assets` endpoint.

Then, make sure to set `WIDGET_VERSION` and `WASM_VERSION` to the correct version of the widget and WASM files you want to serve. This defaults to `latest`, which will serve the latest version of the widget and WASM files, although these are not recommended in production as they might serve breaking changes.

The available versions are the published npm releases of [`@cap.js/widget`](https://www.npmjs.com/package/@cap.js/widget?activeTab=versions) and [`@cap.js/wasm`](https://www.npmjs.com/package/@cap.js/wasm?activeTab=versions). For example:

```env
ENABLE_ASSETS_SERVER=true
WIDGET_VERSION=0.1.58
WASM_VERSION=0.0.8
```

Your assets will be served from the following paths:

* `/assets/widget.js`
* `/assets/floating.js`
* `/assets/cap_wasm_bg.wasm`
* `/assets/hashwx.wasm`
* `/assets/cap_wasm.js`

You can use these in your app by setting the widget's script source to the appropriate path, like this:

```html
<script src="https://<server url>/assets/widget.js"></script>
```

For the floating mode, use:

```html
<script src="https://<server url>/assets/floating.js"></script>
```

And by setting `window.CAP_CUSTOM_WASM_URL` and `window.CAP_CUSTOM_HASHWX_URL` to the paths of the `cap_wasm_bg.wasm` and `hashwx.wasm` files, like this:

```js
window.CAP_CUSTOM_WASM_URL = "https://<server url>/assets/cap_wasm_bg.wasm";
window.CAP_CUSTOM_HASHWX_URL = "https://<server url>/assets/hashwx.wasm";
```

`hashwx.wasm` ships in `@cap.js/wasm` 0.0.8 and newer. With an older `WASM_VERSION`, `/assets/hashwx.wasm` responds with a 503, so leave `CAP_CUSTOM_HASHWX_URL` unset and the widget will load it from jsdelivr.

By default, these fetch from `process.env.CACHE_HOST` (which defaults to `https://cdn.jsdelivr.net`). You can change this by setting the `CACHE_HOST` env variable when running the server.

### Troubleshooting

The assets are downloaded from `CACHE_HOST` into Redis at startup, then refreshed hourly. If an asset endpoint responds with `Asset not cached yet`, the download hasn't happened. Check that:

* `ENABLE_ASSETS_SERVER=true` is actually set on the Cap container. If you changed it in a compose file, recreate the container. When it isn't set, the `/assets/*` endpoints respond with a 404 explaining that the asset server is disabled.
* The container has outbound network access to `CACHE_HOST`. If a download fails, the server logs a line containing `[asset server] failed to update assets cache` at startup and retries every hour.
* `WIDGET_VERSION` and `WASM_VERSION` point to versions that actually exist on npm.

## Rate-limiting

Challenge endpoints are rate-limited per client IP using a fixed window, defaulting to 30 requests every 5 seconds. You can change the global limit under **Settings** in the dashboard (or via `PUT /settings/ratelimit`), and override it per site key in the key's **Configuration** tab. When the limit is exceeded, requests get a `429` response with an `X-RateLimit-Remaining: 0` header.

The `/siteverify` endpoint is intended for server-to-server use, so it's not ratelimited by default.

### Client IPs behind a proxy

Standalone identifies clients by checking the `X-Forwarded-For`, `X-Real-IP` and `CF-Connecting-IP` headers (in that order), falling back to the socket address. If you're behind a reverse proxy that uses a different header, set `RATELIMIT_IP_HEADER` in your env (or the IP header under **Settings > Headers** in the dashboard). For example, behind Cloudflare you might set it to `cf-connecting-ip`.

Make sure your proxy actually forwards the client IP. For nginx:

```nginx
location / {
    proxy_pass http://localhost:3000;
    proxy_set_header X-Forwarded-For $remote_addr;
}
```

Without this, every request appears to come from the proxy's own IP and all clients share a single rate-limit bucket. Also note that `X-Forwarded-For` is trusted as-is, so the server must not be directly reachable from the internet, otherwise clients can spoof the header and bypass rate limiting.

## Redis / Valkey

Cap Standalone uses Redis (or Valkey) for all data storage. Set the `REDIS_URL` environment variable to your Redis connection string. This defaults to `redis://localhost:6379`.

The recommended setup uses Valkey (a Redis-compatible store) via the docker-compose file provided in the [quickstart guide](/guide/standalone/).

If you share a single Redis instance across multiple Cap deployments (or with other apps), set `REDIS_PREFIX` to namespace all keys. For example, `REDIS_PREFIX=cap:` stores sessions as `cap:session:...`, metrics as `cap:metrics:...`, and so on. It's empty by default, so existing deployments are unaffected.

## Health checks and shutdown

Cap Standalone has two unauthenticated endpoints for orchestrators and uptime monitors:

* `GET /health` returns `200 {"status":"ok"}` when Redis answers a `PING` within 2 seconds, and `503 {"status":"unavailable"}` otherwise. Use it for readiness checks and alerts.
* `GET /health/live` returns `200` as long as the process is running, even while Redis is down. Use it for liveness checks, so an orchestrator doesn't restart Cap in a loop during a Redis outage.

Checks that arrive within the same second share one `PING`, so polling `/health` adds no load on Redis.

In Kubernetes:

```yaml
readinessProbe:
  httpGet:
    path: /health
    port: 3000
livenessProbe:
  httpGet:
    path: /health/live
    port: 3000
```

With Docker Compose, add this to the `cap` service. Plain Docker only marks the container as unhealthy, it doesn't restart it.

```yaml
healthcheck:
  test: ["CMD", "bun", "-e", "fetch('http://127.0.0.1:3000/health').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
  interval: 30s
  timeout: 5s
  retries: 3
```

On `SIGTERM` or `SIGINT`, Cap stops accepting connections, lets requests already in progress finish, closes its Redis connection and exits with code 0. If a request is still running after 8 seconds, Cap exits with code 1 anyway, which keeps it inside Docker's default 10-second stop timeout. A second signal exits immediately.

## Error messages

Error messages are redacted by default and instead logged to the console. To disable error logging, set `DISABLE_ERROR_LOGGING=true`. To disable error message redaction, set `SHOW_ERRORS=true`.

## HashWX proof of work

Standalone uses [HashWX](../hashwx.md), a GPU-resistant proof of work, as the default challenge protocol for new keys. It's configured per site key, so individual keys can use SHA-256 while others stay on HashWX. Keys created before HashWX became the default keep whatever they were on until you change them.

To change the protocol, open a key's **Configuration** tab and pick one under **Challenge protocol**. HashWX needs no setup: there's no keypair to generate or persist.

Difficulty is controlled by the **HashWX difficulty** slider, the expected number of hashes a client must compute. It defaults to `1_000_000`, split into four sub-challenges, which measured a 578 ms median on an 8-core desktop in Chrome and 1.1 to 5.9 s on phones. See [the phone measurements](../hashwx.md#phones) before you raise it. The valid range is `50_000`-`5_000_000`.

Clients without WebAssembly cannot solve HashWX. If you need to support them, put that key on SHA-256 proof of work instead, which has a pure-JS fallback.

RSW time-lock puzzles are still selectable for existing deployments, but they are deprecated: a GPU clears about 170 times as many of them per second as a CPU, so they do not deliver the GPU resistance they were added for. The **RSW difficulty** slider sets `t`, the number of sequential squarings, in the range `10_000`-`300_000`, and `RSW_BITS=2048` overrides the modulus size at boot.

::: tip
The widget auto-detects the protocol from the wire format, so switching a key is the only change you need to make. Outside Standalone, cap-core still defaults to SHA-256 PoW unless you opt in.
:::

## Instrumentation challenges

Cap Standalone supports JavaScript instrumentation challenges to defeat proof-of-work solvers, along with options to block headless browsers from solving them. Instrumentation challenges are enabled by default when creating new site keys.

You can toggle instrumentation challenges on or off in your site key config. To block headless browsers, turn on "Attempt to block headless browsers" in the key settings.

Note that high instrumentation levels can significantly reduce generation throughput. We recommend keeping it at level 3 unless you need stronger obfuscation. If you find level 3 is too slow, level 1 is significantly faster on a single core.

## IP database

Country and ASN lookups can use one of three providers, configured under `Settings > IP Data > Country & ASN data` in the dashboard: DB-IP Lite, MaxMind GeoLite2 and IPInfo's API.

For DB-IP and MaxMind, the `.mmdb` files are downloaded into `/usr/src/app/data/` inside the container.

### Docker volume permissions

The container runs as the unprivileged `bun` user (UID 1000). If you bind-mount a host directory onto `/usr/src/app/data`, the host directory must be writable by UID 1000, otherwise the download will fail with `EACCES: permission denied`.

```bash
mkdir -p ./cap-data
sudo chown 1000:1000 ./cap-data
```

```yaml
services:
  cap:
    image: tiago2/cap:latest
    volumes:
      - ./cap-data:/usr/src/app/data
    # ...
```

If you can't change ownership on your host (some platforms like Coolify make this awkward), the simplest alternatives are:

* Skip the bind mount entirely and let Docker manage the data directory — the image already creates it with the correct ownership.
* Use a named volume instead of a bind mount.
* Switch to an IP Data provider that doesn't require any local files.

---

---
url: /guide/widget.md
description: >-
  Cap's client widget requests, solves and displays proof-of-work challenges
  with a native web component and WASM. Client-side docs for the open-source
  CAPTCHA.
---

# Widget

Cap's client-side widget handles requesting, solving and displaying challenges using a native web component and rust-flavoured WASM. It also includes the [programmatic mode](./programmatic).

## Installation

::: code-group

```sh [pnpm]
pnpm add cap-widget
```

```sh [npm]
npm i cap-widget
```

```sh [bun]
bun add cap-widget
```

```html [cdn]
<!--

* you should pin a specific version in production to avoid breaking changes. alternatively, you can also use the standalone asset server
* `cdn.jsdelivr.net` is blocked in some jurisdictions, like some parts of China. if your website needs to be reachable from these jurisdictions, we recommend that you use npm.

-->

<script type="module" src="https://cdn.jsdelivr.net/npm/cap-widget"></script>
```

:::

## Self-hosting the widget

The jsdelivr script tag above is the easiest way to start, and stays the default. If you'd rather not depend on a CDN, you can serve everything from your own domain instead. There are two parts to it: the widget JavaScript, and the WASM files the solver loads at runtime.

### Serving the widget JavaScript

Load the `cap-widget` package from a path you control instead of jsdelivr. You have two options:

* Install it from npm (`pnpm add cap-widget`) and `import "cap-widget"` in your app, letting your bundler serve it alongside your other code. The framework examples below already do this.
* Serve the prebuilt file directly. The [Standalone asset server](./standalone/options#asset-server) exposes it at `/assets/widget.js` once you set `ENABLE_ASSETS_SERVER=true`, so you can point a plain script tag at your own instance:

```html
<script src="https://<your-instance>/assets/widget.js"></script>
```

### Pointing the WASM solver at your own copies

By default the widget fetches its two WASM files (`cap_wasm_bg.wasm` and `hashwx.wasm`) from jsdelivr at solve time. Override the URLs with `window.CAP_CUSTOM_WASM_URL` and `window.CAP_CUSTOM_HASHWX_URL`. Set them before the widget solves a challenge, so the simplest place is an inline script before you load the widget:

```html
<script>
  window.CAP_CUSTOM_WASM_URL = "https://<your-instance>/assets/cap_wasm_bg.wasm";
  window.CAP_CUSTOM_HASHWX_URL = "https://<your-instance>/assets/hashwx.wasm";
</script>

<cap-widget data-cap-api-endpoint="https://<your-instance>/<site-key>/"></cap-widget>

<script src="https://<your-instance>/assets/widget.js"></script>
```

If you use a bundler, set the two globals before the import runs:

```js
window.CAP_CUSTOM_WASM_URL = "https://<your-instance>/assets/cap_wasm_bg.wasm";
window.CAP_CUSTOM_HASHWX_URL = "https://<your-instance>/assets/hashwx.wasm";

import "cap-widget";
```

The URLs can point anywhere you host the files, not just a Standalone instance. The [Standalone asset server](./standalone/options#asset-server) is one way to host them: with `ENABLE_ASSETS_SERVER=true` it serves `/assets/cap_wasm_bg.wasm` and `/assets/hashwx.wasm` (alongside `/assets/widget.js` and `/assets/floating.js`), downloaded once from `CACHE_HOST` and refreshed hourly. Set `WIDGET_VERSION` and `WASM_VERSION` to pin the versions it serves.

::: warning
`hashwx.wasm` only ships in `@cap.js/wasm` 0.0.8 and newer. If your `WASM_VERSION` is older, `/assets/hashwx.wasm` responds with a 503, so leave `CAP_CUSTOM_HASHWX_URL` unset and the widget will load HashWX from jsdelivr.
:::

## Usage

The widget requires a `data-cap-api-endpoint` pointing at your Cap deployment. For Standalone instances, this is:

```
https://<your-instance>/<site-key>/
```

### Vanilla

```html
<form>
  <cap-widget id="cap" required data-cap-api-endpoint="https://<your-instance>/<site-key>/"></cap-widget>
  <button type="submit">Submit</button>
</form>

<script type="module">
  import "https://cdn.jsdelivr.net/npm/cap-widget";

  document.getElementById("cap").addEventListener("solve", (e) => {
    console.log("token:", e.detail.token);
  });
</script>
```

::: tip

When the widget lives inside a `<form>`, it automatically injects a hidden `cap-token` input, and the token is submitted alongside your other fields with no extra JavaScript needed.

:::

### React

```jsx
import "cap-widget";

export default function ContactForm() {
  return (
    <form>
      <cap-widget
        data-cap-api-endpoint="https://<your-instance>/<site-key>/"
        onsolve={(e) => console.log("token:", e.detail.token)}
        onprogress={(e) => console.log(e.detail.progress)}
        onerror={(e) => console.error(e.detail.message)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

::: tip

We recommend using React 19 or later as it improves custom element event handling

:::

### Vue

```vue
<script setup>
import "cap-widget";
</script>

<template>
  <form>
    <cap-widget
      data-cap-api-endpoint="https://<your-instance>/<site-key>/"
      @solve="(e) => console.log('token:', e.detail.token)"
      @progress="(e) => console.log(e.detail.progress)"
      @error="(e) => console.error(e.detail.message)"
    />
    <button type="submit">Submit</button>
  </form>
</template>
```

If you're getting an unknown-component warning, add this to your `vite.config.js`:

```js
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: { isCustomElement: (tag) => tag.startsWith("cap-") },
      },
    }),
  ],
});
```

### Svelte 5

```svelte
<script>
  import "cap-widget";
</script>

<form>
  <cap-widget
    data-cap-api-endpoint="https://<your-instance>/<site-key>/"
    on:solve={(e) => console.log("token:", e.detail.token)}
    on:progress={(e) => console.log(e.detail.progress)}
    on:error={(e) => console.error(e.detail.message)}
  />
  <button type="submit">Submit</button>
</form>
```

### SolidJS

```jsx
import "cap-widget";

export default function ContactForm() {
  return (
    <form>
      <cap-widget
        data-cap-api-endpoint="https://<your-instance>/<site-key>/"
        on:solve={(e) => console.log("token:", e.detail.token)}
        on:progress={(e) => console.log(e.detail.progress)}
        on:error={(e) => console.error(e.detail.message)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

### Astro

```astro
---
// ContactForm.astro
---

<form>
  <cap-widget id="cap" data-cap-api-endpoint="https://<your-instance>/<site-key>/" />
  <button type="submit">Submit</button>
</form>

<script>
  import "cap-widget";

  document.getElementById("cap").addEventListener("solve", (e) => {
    console.log("token:", e.detail.token);
  });
</script>
```

If you're rendering a React/Vue/Svelte component inside Astro, follow that framework's guide above and add `client:load` to the component.

### Preact

```jsx
import "cap-widget";

export default function ContactForm() {
  return (
    <form>
      <cap-widget
        data-cap-api-endpoint="https://<your-instance>/<site-key>/"
        onsolve={(e) => console.log("token:", e.detail.token)}
        onprogress={(e) => console.log(e.detail.progress)}
        onerror={(e) => console.error(e.detail.message)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

### Qwik

```tsx
import { component$ } from "@builder.io/qwik";
import "cap-widget";

export default component$(() => {
  return (
    <form>
      <cap-widget
        data-cap-api-endpoint="https://<your-instance>/<site-key>/"
        on:solve$={(e: CustomEvent) => console.log("token:", e.detail.token)}
        on:progress$={(e: CustomEvent) => console.log(e.detail.progress)}
        on:error$={(e: CustomEvent) => console.error(e.detail.message)}
      />
      <button type="submit">Submit</button>
    </form>
  );
});
```

## Programmatic mode

If you don't want a visible widget, for example when protecting a background action like a post submission, use the [programmatic mode](./programmatic):

```js
import Cap from "cap-widget";

const cap = new Cap({
  apiEndpoint: "https://<your-instance>/<site-key>/",
});

const { token } = await cap.solve();
```

## Events

All events are dispatched as CustomEvent.

| Event      | When it fires                  | Detail                 |
| ---------- | ------------------------------ | ---------------------- |
| `solve`    | Challenge solved successfully  | `{ token: string }`    |
| `progress` | Progress update during solving | `{ progress: number }` |
| `error`    | An error occurred              | `{ message: string }`  |
| `reset`    | Widget reset to initial state  | `{}`                   |

## Options

You can also specify a custom fetch function with `window.CAP_CUSTOM_FETCH`:

```js
window.CAP_CUSTOM_FETCH = (url, params) => fetch(url, params);
```

If you serve the widget under a strict Content-Security-Policy, you can supply nonces so the widget's injected `<style>` and `<script>` elements aren't blocked:

* `window.CAP_CSS_NONCE` — applied to the widget's `<style>` tag. Also used as a fallback nonce for injected scripts if `CAP_SCRIPT_NONCE` is unset.
* `window.CAP_SCRIPT_NONCE` — applied to the scripts the widget injects: the pako decompression fallback and the instrumentation challenge iframe.

You can also set a custom WASM url (for example the Standalone asset server's) with `window.CAP_CUSTOM_WASM_URL`, and the HashWX one with `window.CAP_CUSTOM_HASHWX_URL`. See [self-hosting the widget](#self-hosting-the-widget) for a full example.

To disable haptic feedback (vibrations on mobile devices), set `window.CAP_DISABLE_HAPTICS = true` globally or add the `data-cap-disable-haptics` attribute to individual widgets:

```js
window.CAP_DISABLE_HAPTICS = true;
```

```html
<cap-widget data-cap-disable-haptics data-cap-api-endpoint="..."></cap-widget>
```

Haptic feedback is automatically disabled in [programmatic mode](./programmatic) since there is no visible widget for the user to interact with

### Attributes

| Attribute                      | Description                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `data-cap-api-endpoint`        | **Required.** Your Cap endpoint: `https://<instance>/<site-key>/`             |
| `data-cap-worker-count`        | Number of solver workers (defaults to `navigator.hardwareConcurrency \|\| 8`) |
| `data-cap-hidden-field-name`   | Name of the hidden token input in a `<form>` (default: `cap-token`)           |
| `data-cap-troubleshooting-url` | Custom URL for the "Troubleshooting" link shown when a user is blocked        |
| `data-cap-disable-haptics`     | Disable haptic feedback (vibrations) on this widget                           |

#### i18n

All widget labels can be overridden with `data-cap-i18n-*` attributes. These default to English

```html
<cap-widget
  data-cap-api-endpoint="https://<your-instance>/<site-key>/"
  data-cap-i18n-initial-state="Verify you're human"
  data-cap-i18n-verifying-label="Verifying..."
  data-cap-i18n-solved-label="You're human"
  data-cap-i18n-error-label="Error"
  data-cap-i18n-troubleshooting-label="Troubleshooting"
  data-cap-i18n-wasm-disabled="Enable WASM for significantly faster solving"
  data-cap-i18n-verify-aria-label="Click to verify you're a human"
  data-cap-i18n-verifying-aria-label="Verifying, please wait"
  data-cap-i18n-verified-aria-label="Verified"
  data-cap-i18n-required-label="Please verify you're human"
  data-cap-i18n-error-aria-label="An error occurred, please try again"
></cap-widget>
```

### Styling

Override any of these CSS variables on the `cap-widget` element:

```css
cap-widget {
  --cap-background: #fdfdfd;
  --cap-border-color: #dddddd8f;
  --cap-border-radius: 14px;
  --cap-widget-height: 30px;
  --cap-widget-width: 230px;
  --cap-widget-padding: 14px;
  --cap-gap: 15px;
  --cap-color: #212121;
  --cap-checkbox-size: 25px;
  --cap-checkbox-border: 1px solid #aaaaaad1;
  --cap-checkbox-border-radius: 6px;
  --cap-checkbox-background: #fafafa91;
  --cap-checkbox-margin: 2px;
  --cap-font: system-ui, -apple-system, sans-serif;
  --cap-spinner-color: #000;
  --cap-spinner-background-color: #eee;
  --cap-spinner-thickness: 5px;
}
```

---

---
url: /guide/programmatic.md
description: >-
  Programmatic mode for Cap: call new Cap() and solve() to run the open-source
  CAPTCHA from your own JavaScript, with proof-of-work and no visible widget.
---

# Programmatic mode

You can use `new Cap({ ... })` in your client-side JavaScript to create a new Cap instance and use the `solve()` method to solve the challenge.

```js
const cap = new Cap({
  apiEndpoint: "https://<your-instance>/<site-key>/",
  // or: apiEndpoint: "/api/",
});
const solution = await cap.solve();

console.log(solution.token);
```

You can also set up [event listeners](widget.md#supported-events):

```js
const cap = new Cap({
  apiEndpoint: "https://<your-instance>/<site-key>/",
  // or: apiEndpoint: "/api/",
});

cap.addEventListener("progress", (event) => {
  console.log(`Solving... ${event.detail.progress}% done`);
});
```

Behind the scenes, Cap creates a hidden `cap-widget` element and uses it to solve the challenge.

## Supported methods and arguments

The following methods are supported:

#### `new Cap({ ... })`

Creates a new Cap instance. If a 2nd argument is provided, it will use that element instead of creating a new one in memory.

**Arguments**

```json
{
  apiEndpoint: ..., // api endpoint, similar to the widget `data-cap-api-endpoint` attribute
  workers: navigator.hardwareConcurrency || 8 // number of worker threads to use
}
```

#### `cap.solve()`

Requests and solves a challenge.

**Output:** `{ token }`

#### `cap.token`

Returns the token from the latest solve

#### `cap.reset()`

Resets `cap.token`

#### `cap.addEventListener(..., function () { ... })`

Listens for an event for the cap widget. See [supported events](widget.md#supported-events)

---

---
url: /guide/floating.md
description: >-
  Floating mode for Cap's widget hides the open-source CAPTCHA until a button is
  pressed, then runs proof-of-work on demand. Set it up with one data attribute.
---

# Floating mode

Cap can automatically hide the CAPTCHA until a button is pressed. To use this, add the `data-cap-floating` attribute to your trigger with the query selector of the `cap-widget` element you want to use.

```html
<cap-widget
  id="floating"
  onsolve="console.log(`token: ${event.detail.token}`)"
  data-cap-api-endpoint="<api endpoint>"
></cap-widget>

<button data-cap-floating="#floating" data-cap-floating-position="bottom">
  Trigger floating mode
</button>
```

You'll also need to import both the Cap library and the floating mode script from JSDelivr:

```html{2}
<script src="https://cdn.jsdelivr.net/npm/cap-widget"></script>
<script src="https://cdn.jsdelivr.net/npm/cap-widget/cap-floating.min.js"></script> <!-- [!code ++] -->
```

Or from the standalone server:

```html
<script src="https://<server url>/assets/widget.js"></script>
<script src="https://<server url>/assets/floating.js"></script>
<!-- [!code ++] -->
```

If you want to serve everything from your own domain and keep the solver off the CDN too, see [self-hosting the widget](./widget#self-hosting-the-widget).

The following attributes are supported:

* `data-cap-floating`: The CSS selector of the `cap-widget` element you want to use.
* `data-cap-floating-position`: The position of the floating widget. Can be `top` or `bottom`.
* `data-cap-floating-offset`: The offset of the floating widget from the trigger element.

---

---
url: /guide/capjs-core.md
description: >-
  capjs-core is Cap's stateless server library for generating and verifying JWT
  proof-of-work challenges. Self-host the open-source CAPTCHA on Workers or
  edge.
---

# Core

Cap includes a stateless server-side library for generating and verifying JWT-based challenges, which is used internally for Standalone.

For most users we recommend [Cap Standalone](./standalone/index.md) which runs on Docker and is batteries included. We only recommend using the core library directly when you can't run Docker, want to embed challenge generation into an existing service, or need to deploy to an environment without persistent storage (Cloudflare Workers, Lambda, edge functions).

## Installation

::: code-group

```sh [bun]
bun add capjs-core
```

```sh [npm]
npm i capjs-core
```

```sh [pnpm]
pnpm i capjs-core
```

:::

## Getting started

```js
import { generateChallenge, validateChallenge } from "capjs-core";

// Long, random, high-entropy. Keep this consistent across processes.
const SECRET = process.env.CAP_SECRET;

// 1) Server route: create a challenge
const ch = await generateChallenge(SECRET, {
  scope: "signup", // optional
  instrumentation: true, // optional, see below
});
// → { challenge: { c, s, d }, token, expires, instrumentation? }

// 2) Server route: validate the redeemed challenge
const result = await validateChallenge(
  SECRET,
  {
    token: req.body.token,
    solutions: req.body.solutions,
    instr: req.body.instr,
  },
  {
    scope: "signup",
    consumeNonce: async (sigHex, ttlMs) => myStore.setIfNotExists(`cap:${sigHex}`, 1, ttlMs),
  },
);

if (result.success) {
  // result.token, result.tokenKey, result.expires, result.scope
}
```

The widget calls `generateChallenge` to receive `{ challenge, token, expires, instrumentation }`, solves the proof of work client-side, and POSTs `{ token, solutions, instr }` back. You then call `validateChallenge` to verify.

## How it differs from `@cap.js/server`

| Aspect            | `@cap.js/server`                          | `capjs-core`                                |
| ----------------- | ----------------------------------------- | ------------------------------------------- |
| State             | In-memory + filesystem token store        | Stateless. Challenge tokens are signed JWTs |
| Constructor       | `new Cap({ ... })`                        | None — pass `secret` per call               |
| Replay prevention | Built-in token list with cleanup interval | Opt-in via `consumeNonce` callback          |
| Cleanup hooks     | `SIGINT`/`beforeExit` flush               | None — TTL is encoded in JWT `exp`          |
| Filesystem        | Required for persistence                  | Never touched                               |
| Worker compatible | No (filesystem)                           | Yes                                         |

Unlike the old library, `capjs-core` does not validate redeem tokens for you - it returns a `tokenKey` you store yourself, and a `token` you give the user. To validate later, re-derive the key from the user's submitted token and look it up:

```js
import { createHash } from "node:crypto";

// Validation route
const [id, verToken] = req.body.token.split(":");
const tokenKey = `${id}:${createHash("sha256").update(verToken).digest("hex")}`;
const expires = await myStore.get(`cap-token:${tokenKey}`);
if (!expires || Number(expires) < Date.now()) {
  return res.status(401).end();
}
```

## API

### `generateChallenge(secret, opts?)`

Returns `Promise<{ challenge, token, expires, instrumentation? }>`.

* `secret` — string or Buffer, ≥16 bytes. Master HMAC key, must be consistent across processes.
* `opts.challengeCount` — number of PoW puzzles. Default `50`.
* `opts.challengeSize` — salt length in hex chars. Default `32`.
* `opts.challengeDifficulty` — target prefix length in hex chars. Default `4`.
* `opts.expiresMs` — challenge TTL. Default `600_000` (10 min).
* `opts.scope` — optional string bound to the challenge. Validation must pass the same `scope`.
* `opts.extra` — optional object embedded in the JWT payload (visible to anyone with the token).
* `opts.instrumentation` — `true` for defaults, or an object: `{ blockAutomatedBrowsers, obfuscationLevel }`.
* `opts.instrumentationGenerator` — escape hatch for offloading script generation to a worker pool.

The `token` is a signed JWT containing the challenge config. `expires` is the JWT expiry in ms. `instrumentation`, if requested, is the deflate+base64 client-side script to be run by the widget.

### `validateChallenge(secret, body, opts?)`

Returns `Promise<{ success: true, token, tokenKey, expires, scope, iat, riskFlags } | { success: false, reason, instr_error?, blockedBy? }>`.

`riskFlags` lists non-gating automation signals from instrumentation (currently only `native_tamper`), useful for raising difficulty on the next challenge. `blockedBy` is set when `reason` is `instr_automated_browser` and names the detection checks that failed.

`body`:

* `token` — challenge token from `generateChallenge`
* `solutions` — number array, length must equal `challenge.c`
* `instr` — instrumentation result (if you enabled it)
* `instr_blocked`, `instr_timeout` — flags from the widget when instrumentation rejected the page

`opts`:

* `scope` — must match the original challenge's scope
* `tokenTtlMs` — TTL for the redeem token. Default `1_200_000` (20 min).
* `consumeNonce(sigHex, ttlMs)` — replay prevention via your storage. See below.
* `signToken(data)` — async fn returning a custom redeem token format. By default returns `id:secret`.

#### Failure reasons

| `reason`            | meaning                                                   |
| ------------------- | --------------------------------------------------------- |
| `invalid_body`      | body isn't an object                                      |
| `missing_token`     | no token provided                                         |
| `missing_solutions` | solutions missing or not an array                         |
| `invalid_token`     | JWT signature mismatch / malformed / out-of-bounds params |
| `scope_mismatch`    | token's scope doesn't match `opts.scope`                  |
| `expired`           | challenge JWT expired                                     |
| `invalid_solutions` | length mismatch or non-numbers                            |
| `nonce_store_error` | `consumeNonce` callback threw                             |
| `already_redeemed`  | `consumeNonce` returned `false`                           |
| `invalid_solution`  | solutions don't satisfy the PoW                           |
| `instr_*`           | instrumentation failed (with `instr_error: true`)         |

## Replay prevention

The library is stateless by design. To prevent a captured submission from being redeemed twice, pass a `consumeNonce` callback. `capjs-core` calls it with the JWT's signature hex and the remaining TTL; you store that hex in your KV with `SET NX EX` semantics and return `false` on repeats.

::: code-group

```js [redis]
import { Redis } from "ioredis";
const redis = new Redis(process.env.REDIS_URL);

const consumeNonce = async (sigHex, ttlMs) => {
  const ttlSec = Math.ceil(ttlMs / 1000);
  const ok = await redis.set(`cap:${sigHex}`, "1", "NX", "EX", ttlSec);
  return ok === "OK";
};
```

```js [cloudflare-kv]
const consumeNonce = async (sigHex, ttlMs) => {
  const key = `cap:${sigHex}`;
  if (await env.NONCES.get(key)) return false;
  await env.NONCES.put(key, "1", {
    expirationTtl: Math.ceil(ttlMs / 1000),
  });
  return true;
};
```

```js [postgres]
const consumeNonce = async (sigHex, ttlMs) => {
  const expiresAt = new Date(Date.now() + ttlMs).toISOString();
  try {
    await db`INSERT INTO cap_nonces (sig, expires_at) VALUES (${sigHex}, ${expiresAt})`;
    return true;
  } catch (e) {
    if (e.code === "23505") return false; // unique violation
    throw e;
  }
};
```

:::

The check runs *after* PoW and instrumentation verification, so an attacker who replays a captured submission with garbage solutions can't burn the legitimate user's nonce.

## Instrumentation

Pass `instrumentation: true` (or an options object) to `generateChallenge` to receive a deflate+base64 client script. The widget runs it, sends back a fingerprint, and `validateChallenge` verifies it.

```js
const ch = await generateChallenge(SECRET, {
  instrumentation: {
    blockAutomatedBrowsers: true, // reject playwright/puppeteer/selenium
    obfuscationLevel: 3, // 1-10, default 3
  },
});
```

When `blockAutomatedBrowsers` is on, the script runs realm-escape and marker checks in the browser and ships a probe vector (text metrics, window geometry, `navigator.webdriver`, engine markers) that the server evaluates with `detectAutomation`. The server-side verdict is what blocks. See [Instrumentation](./instrumentation.md) for the full check list and what each one is safe against.

`detectAutomation(vector)` is exported for callers who want to run the detector over a vector they collected themselves. It returns `{ pass, checks, blockedBy, riskFlags }`.

Higher obfuscation levels are slower to generate. Levels 4–7 add a custom string-table indirection plus esbuild minification. Levels 8–10 layer in `javascript-obfuscator` (string-array, control-flow flattening, dead-code injection) — these block the event loop for tens of milliseconds per challenge, so use them only for low-volume routes or supply your own `instrumentationGenerator` that runs in a worker pool.

## Stateless deployment patterns

**Warning:** These scripts don't include built-in replay protection. Make sure to add it yourself.

### Cloudflare Workers

```js
import { generateChallenge, validateChallenge } from "capjs-core";

const SECRET = (env) => env.CAP_SECRET;

export default {
  async fetch(req, env) {
    const url = new URL(req.url);

    if (url.pathname === "/challenge" && req.method === "POST") {
      const ch = await generateChallenge(SECRET(env), { instrumentation: true });
      return Response.json(ch);
    }

    if (url.pathname === "/redeem" && req.method === "POST") {
      const body = await req.json();
      const result = await validateChallenge(SECRET(env), body, {
        consumeNonce: async (sigHex, ttlMs) => {
          if (await env.NONCES.get(`cap:${sigHex}`)) return false;
          await env.NONCES.put(`cap:${sigHex}`, "1", {
            expirationTtl: Math.ceil(ttlMs / 1000),
          });
          return true;
        },
      });
      return Response.json(result);
    }

    return new Response("not found", { status: 404 });
  },
};
```

### Bun

```js
import { generateChallenge, validateChallenge } from "capjs-core";
const SECRET = process.env.CAP_SECRET;

Bun.serve({
  port: 3000,
  routes: {
    "/challenge": {
      POST: () => Response.json(generateChallenge(SECRET, { instrumentation: true })),
    },
    "/redeem": {
      POST: async (req) => {
        const body = await req.json();
        return Response.json(await validateChallenge(SECRET, body));
      },
    },
  },
});
```

## HashWX challenges {#format-2-hashwx}

Since v0.1.1 and widget v0.1.51, both pieces understand a richer wire format that supports multiple challenge protocols in a single response: SHA-256 PoW (the default), [HashWX](./hashwx.md), the deprecated RSW time-lock puzzle, and instrumentation.

### Minimum opt-in

```js
import { generateChallenge, validateChallenge } from "capjs-core";

const SECRET = process.env.CAP_SECRET;

app.post("/api/challenge", async () => {
  return await generateChallenge(SECRET, {
    format: 2,
    protocols: ["hashwx", "instrumentation"],
    hashwxDifficulty: 1_000_000, // optional, this is the default
  });
});

app.post("/api/redeem", async (req) => {
  return await validateChallenge(SECRET, req.body, { consumeNonce });
});
```

HashWX needs no key material and no setup at boot. The first verification compiles the embedded WebAssembly module, which takes a few milliseconds; call `hashwxReady()` at startup to move that off the first request.

Runtimes that forbid compiling WebAssembly at runtime need the module precompiled. On Cloudflare Workers this is automatic since v0.1.4: Wrangler resolves the package's `workerd` condition and imports the bundled `hashwx.wasm` directly. On other such runtimes, import `capjs-core/hashwx.wasm` as a `WebAssembly.Module` the way your platform supports and hand it over before the first verification:

```js
import { setHashwxModule } from "capjs-core";
import hashwxModule from "capjs-core/hashwx.wasm";

setHashwxModule(hashwxModule);
```

`hashwxDifficulty` is the expected number of hashes a client must compute, split across `hashwxChallengeCount` independent sub-challenges (default `4`). One challenge on its own has an exponentially distributed solve time, so one visitor waits 30 ms and the next waits three seconds. At the same total difficulty, four sub-challenges cut the p90 by about a quarter and make the median about a third slower, since the attacker's expected work stays `d` hashes either way. See [client cost](./hashwx.md#cost). Each extra sub-challenge adds about 20 µs to verification. `hashwxNoncesPerHash` (default `65_536`) is also accepted.

---

---
url: /guide/community.md
description: >-
  Community-maintained libraries for using Cap, the self-hosted open-source
  CAPTCHA, in more languages and frameworks. Verify proof-of-work tokens outside
  SDKs.
---

# Community libraries

Want to use Cap without the standalone server and with a different language? Here are some community-maintained libraries that might help. If you want to add a library, feel free to open a pull request!

**Note:** These libraries frequently do **not** support new features such as seeded challenges or instrumentation challenges.

## Widgets

These are wrappers around Cap's widget. They're usually not required as the default widget should work everywhere but can result in a better development experience.

### React

* **[@pitininja/cap-react-widget](https://www.npmjs.com/package/@pitininja/cap-react-widget)**
* **[cap-widget](https://ui.ednesdayw.com/docs/components/cap-widget)**: A headless, shadcn-compatible React component for CAP

### Angular

* **[@espressotutorialsgmbh/cap-angular-widget](https://www.npmjs.com/package/@espressotutorialsgmbh/cap-angular-widget)**

### Vue

* **[nuxt-cap](https://github.com/dethdkn/nuxt-cap)**

### Other

* **[better-captcha](https://www.better-captcha.dev/docs/provider/cap-widget)**: A framework-agnostic widget that supports 6 different frameworks including React, SolidJS, Vue, Svelte and more

## Hooks

These are React hook implementations of the Cap API, allowing full customization of the user experience.

* **[@takeshape/use-cap](https://www.npmjs.com/package/@takeshape/use-cap)**

## Server

**Warning:** These libraries are community-maintained and not officially supported or actively monitored for security by Cap. We can't guarantee their quality, security, or compatibility. They also might not support newer features such as storage hooks or seeded challenges.

### Cloudflare Workers (Serverless/JavaScript)

* **[kaerez/CFCap](https://github.com/kaerez/CFCap)**: Serverless CAP CAPTCHA implementation on Cloudflare Workers with R2 Buckets (cheaper than Durable Objects), featuring customizable TTLs, optional use of hosted JS & WASM, global edge deployment and auto-scaling

### Cloudflare Workers (Serverless/JavaScript/TypeScript)

* **[xyTom/cap-worker](https://github.com/xyTom/cap-worker)**: Serverless CAP CAPTCHA implementation on Cloudflare Workers with Durable Objects, featuring global edge deployment and auto-scaling

### Java

* **[luckygc/cap-server](https://github.com/luckygc/cap-server)**: Replacement of wuhunyu's Java server that fixes [an important issue](https://github.com/tiagozip/cap/issues/69#issuecomment-3079407189)

* **[wuhunyu/cap-server-java](https://github.com/wuhunyu/cap-server-java)**

* **[schwebke/cap-captcha-keycloak](https://github.com/schwebke/cap-captcha-keycloak)**: Keycloak extension providing Cap captcha validation for the registration flow

### Go

* **[samwafgo/cap\_go\_server](https://github.com/samwafgo/cap_go_server)**
* **[ackcoder/go-cap](https://github.com/ackcoder/go-cap)**

### Python

* **[capjs-server](https://github.com/vshn/capjs-server)**: Stateless Python server library for Cap token verification (no database required)
* **[django-cap](https://pypi.org/project/django-cap/)**: Python implementation for Cap's server with Django

### .NET

* **[izanhzh/pow-cap-server](https://github.com/izanhzh/pow-cap-server)**

### PHP

* **[clysss/capito](https://github.com/clysss/capito)**: Capito Cap PHP Server
* **[trilbymedia/cap-php](https://github.com/trilbymedia/cap-php)**: PHP port of the Cap proof-of-work captcha server
* **[oliweb-proof-of-work-for-cap](https://github.com/oli217/oliweb-proof-of-work-for-cap)**: WordPress plugin integrating Cap into comments, login, registration and WooCommerce checkout — supports both visible widget and invisible (programmatic) mode
* **[laravel-cap](https://github.com/oli217/laravel-cap)**: Laravel integration for Cap — Blade directives, middleware, validation rules and facade for server-side token verification (`composer require oliweb/laravel-cap`)
* **[statamic-cap](https://github.com/oli217/statamic-cap)**: Statamic addon integrating Cap into forms — widget rendering, automatic token validation and flexible CP configuration (`composer require oliweb/statamic-cap`)
* **[cap-captcha-wordpress](https://github.com/forge28labs/cap-captcha-wordpress)**: A WordPress plugin to integrate Cap into the auth flows, as well as on new comments. Configurable (instance, keys and colors) through the WordPress admin panel.
* **[cap-bundle](https://github.com/silarhi/cap-bundle)**: Symfony bundle integrating Cap into forms, with a form type (checkbox or invisible mode), a validator constraint for server-side token verification, and support for Turbo and Stimulus ([docs](https://cap-bundle.silarhi.dev))

## Client

**Warning:** These libraries are community-maintained and not officially supported or actively monitored for security by Cap. We can't guarantee their quality, security, or compatibility.

### JavaScript

* **[cap-client](https://codeberg.org/sanin/cap-client)**: Client library and express middleware for making verification requests, intended for NodeJS

---

---
url: /guide/effectiveness.md
description: >-
  How effective Cap is against bots: the open-source CAPTCHA pairs proof-of-work
  with instrumentation to make abuse expensive while staying invisible to users.
---

# Effectiveness

## Privacy & security

Cap doesn't use cookies or any type of telemetry by default. No data is collected or stored on any central servers as it's fully self-hosted.

Cap includes replay protection and signature-based challenge tokens by default.

## Why proof-of-work?

Every CAPTCHA can eventually be solved, whether by AIs, algorithms, reverse-engineering and spoofing fingerprints, or humans paid via CAPTCHA farms, and this results in an endless cat-and-mouse game between attackers and defenders. The crucial difference lies in the cost imposed on attackers.

Cap's goal is to make automated abuse expensive and hard while keeping the experience fast and virtually invisible for real users. Proof-of-work is a perfect balance for this issue, stopping abuse by requiring computational effort rather than relying solely on human verification methods that bots continuously learn to mimic.

Imagine sending 10,000 spam messages costs $1, potentially earning $10 – a profitable venture. If Cap increases the computational cost so that sending those messages now costs $100, the spammer loses $90. This eliminates the financial incentive.

Cap's proof-of-work is heavily inspired by [Hashcash](https://www.researchgate.net/publication/2482110_Hashcash_-_A_Denial_of_Service_Counter-Measure). Our instrumentation challenges are inspired by Twitter and YouTube's own custom challenges.

## Making GPUs useless

SHA-256 is reasonable as a general PoW algorithm, but a GPU clears roughly 150 times as many of them per second as a CPU. That's why new keys default to [HashWX](./hashwx.md), where the gap is about 2x.

## See also

* [CAPTCHA and conversion rate](./captcha-conversion-rate.md): what challenge friction costs in signups
* [Best CAPTCHA alternatives in 2026](./best-captcha-alternatives.md): how other mechanisms compare

---

---
url: /guide/instrumentation.md
description: >-
  Cap's instrumentation challenges run server-generated JS to verify a real
  browser, working alongside proof-of-work in the self-hosted, open-source
  CAPTCHA.
---

# Instrumentation challenges

Instrumentation challenges are Cap's second layer of verification, running silently alongside the core proof-of-work system and present on Cap Standalone.

They generate a unique JavaScript program on every request that is executed inside the visitor's browser. The output is checked server-side, allowing Cap to confirm that a genuine browser environment is present before accepting a token.

## How they work

When a challenge is issued, the server generates a self-contained JavaScript bundle that runs a few browser API probes and evaluates a main computation chain, where multiple integer variables are initialised with random seed values and then mutated through randomised operations, including bitwise AND/OR/XOR/NAND, prototype-chain tricks, and DOM-based arithmetic that appends a tree of elements to the page, walks back up it accumulating values, and then removes them.

The server tracks the expected result of every operation in parallel, so it knows what the final four values must be.

All of these checks run inside an iframe, which `postMessage`s the answers back to the parent.

## Why DOM operations

Pure arithmetic can be replicated in a non-browser environment by simply running the JavaScript. DOM operations cannot - or at least, not cheaply. Constructing real element trees, reading values through the browser's layout engine, and tearing them down again exercises a part of the browser that non-browser runtimes often stub out, do incorrectly, or skip entirely for performance. This makes the challenge harder to replay outside a genuine rendering engine.

Instrumentation challenges often also mix these with a preset list of checks.

## Automated browser detection

With `blockAutomatedBrowsers` enabled, the instrumentation script also collects a small vector of browser facts (text metrics, window geometry, `navigator.webdriver`, engine markers) and ships it back with the computation result. The server runs the detector over that vector. A client-side-only check is a suggestion that a stealth browser patches out, so nothing here trusts the client's own verdict.

Seven checks can fail a request. Every one of them targets the automation layer or tampering, never which browser build you run. Widevine, H.264, `userAgentData` brand and similar build identity signals are not used to block, because a person on ungoogled-chromium looks identical to a stealth driver on the same binary in those fields.

| Check | What it catches | Why it is safe for humans |
| --- | --- | --- |
| `geometry_quantized` | Camoufox snaps text advance widths to whole pixels. Real Blink, Gecko and WebKit return fractional widths, and Firefox's resist-fingerprinting mode does not round them either. | Requires at least 5 of 17 font stacks to be whole pixels **and** at least 2 distinct integer values, so a single-font system cannot trip it. |
| `webdriver_true` | Plain Selenium, Playwright, Puppeteer, rebrowser. | Spec-defined automation flag. No shipping browser sets it. |
| `webdriver_stripped` | Stealth patches that delete `navigator.webdriver` on Chromium. | Real Chrome always exposes it as `false`. |
| `gecko_contradiction` | Spoofers exposing `navigator.deviceMemory` or `userAgentData` on a Gecko engine. | Firefox has never shipped either API. |
| `window_exceeds_screen` | CDP `Emulation.setDeviceMetricsOverride` shrinks `screen` to the viewport and leaves the window taller than the display. | Skipped when `screen.isExtended` is true, so a taller second monitor passes. |
| `viewport_override` | Viewport exactly equal to the screen while browser chrome is present. | Skipped on mobile, where a full-screen viewport is normal. |
| `headless_token` | `HeadlessChrome` in the UA or `userAgentData.brands`. | No consumer browser exposes it. |

Two more signals are collected but never block:

* `native_tamper`: `Function.prototype.toString` on canvas, WebGL and permissions methods is no longer `[native code]`. This catches puppeteer-stealth and selenium-stealth, but privacy extensions (Canvas Blocker, Chameleon, Trace) patch the exact same methods. It is returned as a risk flag so you can raise proof-of-work difficulty instead of blocking.
* Browser-surface clusters (no `window.chrome`, no plugins, no PDF viewer) are not used at all. Mobile Chrome and Android WebView legitimately match all three.

When a request is blocked, `validateChallenge` returns `reason: "instr_automated_browser"` with a `blockedBy` array naming the failed checks. Successful validations carry `riskFlags`. Cap Standalone surfaces the same reason as `automated_browser_detected`.

Known gaps: `undetected-chromedriver` and `nodriver` driving a headful stock Chrome pass all seven checks. Headless Firefox passes too, since Gecko has no `HeadlessChrome` equivalent. Even commercial CAPTCHAs like Turnstile are bypassed by these tools, and proof-of-work remains the layer that makes such traffic expensive.

Open false-positive risks that have not been measured yet: Tor Browser's text metric rounding against `geometry_quantized`, and mixed-DPI multi-monitor setups against `window_exceeds_screen`. If you run either and see blocks, please open an issue with the `blockedBy` value.

## Relationship to proof-of-work

Instrumentation challenges and proof-of-work are complementary, not redundant. Proof-of-work proves *effort*: the client had to burn CPU cycles to find a hash. Instrumentation proves *environment*: the computation happened inside a browser, not a script. Together they raise the cost of abuse on two independent axes - neither alone is sufficient against a determined attacker, but both together are substantially harder to defeat simultaneously.

Instrumentation is not foolproof. While challenges like these are deployed at massive scale by platforms such as [YouTube](https://www.reddit.com/r/youtubedl/comments/1mkzmp3/what_is_a_po_token/) and [Twitter](https://x.com/i/js_inst), I do not recommend using them as a replacement for proof-of-work. Without PoW and with real browsers, attackers can cheaply mine these challenges.

---

---
url: /guide/hashwx.md
description: >-
  HashWX is Cap's GPU-resistant proof of work. Each challenge generates a fresh
  hash function, so a GPU gains about 2x over a CPU instead of 150x.
---

# HashWX proof of work

**HashWX** is Cap's default challenge protocol. Instead of a fixed hash function like SHA-256, every challenge generates a **new** one-way function from a seed, built out of integer operations and branches chosen so that a GPU cannot run it much faster than a CPU.

It was designed by [tevador](https://github.com/tevador/hashwx), who also wrote RandomX and HashX. Cap vendors the reference WebAssembly build.

::: tip
HashWX is the default for new Standalone keys. In cap-core it is opt-in through the format-2 API, and SHA-256 proof of work stays the default there. See [HashWX challenges](./capjs-core.md#format-2-hashwx).
:::

## Why HashWX

The problem with SHA-256 proof of work is throughput. A GPU runs the same fixed function across thousands of lanes in lockstep, so it solves far more challenges per second than a CPU. That is the metric that matters for bot protection: an attacker does not care how long one challenge takes, only how many they can clear per hour.

Cap previously shipped RSW time-lock puzzles for this. RSW wins on **latency**, since sequential squaring cannot be parallelised within one puzzle, but it loses badly on **throughput**, because a GPU can run thousands of independent puzzles at once. Measured against a consumer GPU:

| Algorithm | CPU, Ryzen 3700X, 16 threads | GPU, RTX 5060 Ti | GPU advantage |
|---|---:|---:|---:|
| SHA-256 | 41 MH/s | 6150 MH/s | ~150x |
| RSW | 26 H/s | 4400 H/s | ~170x |
| **HashWX** | **2.8 MH/s** | **5.8 MH/s** | **~2x** |

Those figures are tevador's, using his own non-public CUDA implementation. We reproduced the RSW row independently: an M3 measures 2.112 H/s per thread, which lands on 26 H/s for 16 Ryzen threads.

RSW is deprecated. It is still selectable per key, and existing keys keep working, but it should not be used for new deployments.

## How the protocol works

### Mint

The server picks 32 random bytes as the challenge `C` and a difficulty `d`. There is no key material and no precomputation, so minting is a random read and a JWT sign.

The client is given `C`, `d`, and `n`, the number of nonces each generated function covers.

### Client solve

The client finds a 64-bit nonce `N` such that

```
H(N) <= (2^64 - 1) / d      where H = hashwx_make(sha256(C || u64le(N / n)))
```

Each block of `n` consecutive nonces shares one generated hash function. The client builds that function, runs it over the block, and moves to the next block if nothing lands under the target. Expected work is `d` hashes.

Cap uses `n = 65536`. The reference protocol uses 463 for native clients; in a browser the function has to be JIT-compiled through `WebAssembly.Module` for every block, so a larger block amortises that cost. tevador notes the tradeoff explicitly: more nonces per function makes the protocol somewhat more susceptible to JIT-compiled GPU kernels, and divergent branching is what still carries the GPU resistance at that setting. The ~2x figure above is measured at 65536, so it already accounts for this.

### What makes it GPU-resistant

Four properties, all from the [design document](https://github.com/tevador/hashwx/blob/master/doc/design.md):

Each instance is 32 programs, each a loop that branches back to its own start with probability 1/2, which works out to exactly 256 branches per hash. On a CPU that is a handful of mispredictions. On a GPU it splits a warp into divergent paths that have to be executed one after another.

There is a 16 KB scratchpad and its loads are deliberately unaligned. A CPU keeps it in L1 and hides the 3 to 4 cycle latency by reordering. A GPU has to keep it in local memory backed by L2 at around 100 cycles, and most GPU architectures have to emulate unaligned loads by combining two adjacent ones.

Source registers are drawn from interleaved "shallow" and "deep" lists, so a CPU handles 2.75 dependent loads on average. A GPU interpreter has to specialise for the deep list, because in about 95% of cases at least one thread in a warp is running a deep program, so it eats the full chain of 6 dependent loads every time.

The instruction set is restricted to what WebAssembly 1.0 offers: 64-bit multiply, add, subtract, XOR, OR, rotate and shift, with 6-bit immediates. That is what lets the same algorithm run in a browser at all.

### Server verify

The server recomputes the seed from `C` and the block index implied by the submitted nonce, generates that one hash function, runs it once, and compares against the target. Program generation is about 5x cheaper than HashX, which is what keeps verification in the tens of microseconds.

## Cost

Server cost per challenge, measured on one core of an Apple M3, median over 200 mints and 40 verifications through `validateChallenge`:

| Protocol | Mint | Verify | Total |
|---|---:|---:|---:|
| **HashWX**, 1 challenge | **14 µs** | **40 µs** | **54 µs** |
| **HashWX**, 4 sub-challenges (default) | **20 µs** | **129 µs** | **149 µs** |
| SHA-256 (50 challenges, difficulty 4) | 4 µs | 83 µs | 87 µs |
| RSW (t = 75,000) | 1522 µs | 14 µs | 1536 µs |

A single HashWX challenge is the cheapest round trip of the three. The default of four sub-challenges costs about 150 µs, more than SHA-256 but a tenth of RSW, which pays for four real modular exponentiations on every mint. Difficulty does not change these numbers: verifying is one hash per sub-challenge however hard it was to find.

Client cost is the other side of that trade. One challenge on its own has an exponentially distributed solve time, which makes it a lottery: the same difficulty takes 30 ms for one visitor and three seconds for the next. So by default Cap splits the difficulty into four sub-challenges, which evens the solve time out. Measured through the widget in release Chrome on an M3 with 8 cores, 72 solves each, with the two difficulties tuned to about the same median:

| | 1 challenge, d = 1,330,000 | 4 sub-challenges, d = 1,000,000 |
|---|---:|---:|
| Median | 536 ms | 490 ms |
| p90 | 1447 ms | 778 ms |
| Slowest of 72 | 2378 ms | 1490 ms |

The right-hand column is the default. Against a Standalone key it measured a 578 ms median and a 0.9 s p90.

Splitting does not change what an attacker pays for a given difficulty, since the expected work is `d` hashes however it is cut. What changes is the shape. The median of one challenge sits at 0.69 of its mean, while four sub-challenges put it at about 0.92 of the mean and shorten the tail. At the same difficulty, then, the split makes the typical solve about a third slower and cuts the p90 by about a quarter. The table holds the median fixed instead, which puts the split at 25% less difficulty and gives an attacker 25% less work per solve. The widget's own overhead is small. Its workers check for a stop every 16 ms, which bounds how long a handoff between sub-challenges can take.

### Browser engines

The wasm build runs at roughly 60% of native speed. The three major engines are close on a single worker, and Safari falls behind once every core is busy. Measured on the same M3 in one session, with each browser headless or in front:

| Engine | 1 worker | 8 workers | Interpreted fallback |
|---|---:|---:|---:|
| Chrome 153 | 440 KH/s | 2050 KH/s | 94 KH/s |
| Firefox 156 | 420 KH/s | 1850 KH/s | 105 KH/s |
| Safari 27.2 | 410 KH/s | 1480 KH/s | 105 KH/s |

On one worker all three are within 5% of each other. On eight, Safari reaches about 70% of Chrome's rate, so tune the difficulty against Safari: at d = 1,000,000 that is a mean of about 0.5 s on Chrome and 0.7 s on Safari.

If you benchmark this yourself, measure a release build of each browser with the tab in front. Playwright's bundled Firefox runs every WebAssembly workload three to six times slower than release Firefox, not just HashWX, and a backgrounded tab can land on the efficiency cores and halve every number.

### Phones

The default on real phones through BrowserStack, 15 solves each and 30 on the Vivo. Every run started on a freshly loaded page, the way a visitor arrives. Once the page had already run HashWX for a minute, the Pixel 6 took 24% less time per solve and the Vivo 29% less, so a benchmark that warms up first will look better than this.

| Device | OS | All cores | Median | Slowest |
|---|---|---:|---:|---:|
| Galaxy S24 | Android 14 | 1238 KH/s | 1.1 s | 1.8 s |
| Pixel 9 | Android 15 | 837 KH/s | 1.4 s | 2.0 s |
| Pixel 6 | Android 12 | 746 KH/s | 1.9 s | 2.4 s |
| iPhone 15 | iOS 17 | not measured | 1.9 s | 4.3 s |
| iPhone 12 | iOS 17 | 620 KH/s | 2.0 s | 3.3 s |
| iPhone 13 | iOS 15 | 678 KH/s | 2.2 s | 4.1 s |
| iPhone SE 2022 | iOS 15 | 588 KH/s | 2.4 s | 4.0 s |
| Redmi Note 11 | Android 11 | 456 KH/s | 2.4 s | 4.8 s |
| Galaxy M32 | Android 11 | 444 KH/s | 2.8 s | 6.1 s |
| Vivo Y21 | Android 11 | 316 KH/s | 5.9 s | 11.0 s |

Each solve includes two round trips to the test server, with a median of 80 to 190 ms per device. The Vivo, a budget Android, takes about ten times as long as the M3 desktop. If most of your traffic is mobile, lower the difficulty. Solve time scales linearly with it, so 500,000 roughly halves the solving part of every number here.

Clients without WebAssembly cannot solve HashWX at all and will get an error. If you need to support them, use SHA-256 proof of work, which has a pure-JS fallback. On iPhones the widget needs iOS 15 or newer.

## What HashWX does not protect against

The same thing RSW did not: custom silicon. An FPGA or ASIC built for this would still beat a CPU. The economics do not work for CAPTCHA farming, since an ASIC costs millions in non-recurring engineering, but it is not a cryptographic guarantee.

It also does not stop a human solving farm, and it never will. Proof of work raises the cost per request. Pair it with [instrumentation challenges](./instrumentation.md) so that a real browser environment is required as well.

## Trying it

The cap-core API is documented in [HashWX challenges](./capjs-core.md#format-2-hashwx). The widget auto-detects format-2 responses, so upgrading the server is enough.

On [Cap Standalone](./standalone/options.md#hashwx-proof-of-work), HashWX is the default for new keys and can be switched per key in the dashboard.

---

---
url: /guide/workings.md
description: >-
  How Cap works under the hood: the self-hosted CAPTCHA generates seeded
  proof-of-work challenges, solves them in WASM, then redeems a signed token on
  the server.
---

# How does Cap work?

By the way, this is a more technical explanation of how Cap's SHA-256 and instrumentation challenges work. It doesn't include [HashWX](./hashwx.md). If you're looking for a more general overview, check out the [Effectiveness](./effectiveness.md) page.

***

1. When Cap is initialized, it automatically registers a custom element for the widget in the browser
2. The widget creates a shadow DOM and appends all necessary elements to it

#### Requesting the challenge

3. When a solution is requested, the widget sends a request to the server. The server will return a token, the configuration for the challenges to solve and optionally compressed instrumentation data.

4. The widget then generates multiple challenges using a set seed (the challenge token) and the configuration provided by the server. If instrumentation data is provided, it's decompressed and solved in a sandboxed iframe.

#### Computing the solution

5. The widget uses Rust-flavoured WASM and Web Workers to solve the challenges in parallel:
   * Each worker attempts to find a valid nonce by repeatedly:
     * Combining the salt with different nonce values
     * Computing the SHA-256 hash of this combination
     * Checking if the resulting hash begins with the target prefix
   * The WASM increments the nonce until a matching hash is found

6. Instrumentation challenges are decompressed and executed, if present.

#### Redeeming the solution for a token

7. Once a valid solution is found, the widget sends the result back to the server for validation.
8. The server itself then also generates the same challenges using the provided token and configuration, and verifies the solutions submitted by the widget.
9. Upon successful verification, the server redeems the solution and issues a token that can be used to authenticate the request.

---

---
url: /guide/benchmark.md
description: >-
  Cap CAPTCHA benchmark: proof-of-work solve times across low-end to high-end
  devices. See how fast the self-hosted, open-source widget runs in real
  browsers.
---

# Benchmark

## Benchmark results

These use a placeholder server, speeds might vary depending on your setup and network latency.

A challenge difficulty of 4 with 50 challenges on WASM 0.0.7 was used to run these benchmarks.

| Tier      | Device             | Time |
| --------- | ------------------ | ------ |
| Low-end   | Samsung Galaxy A34 | 795ms  |
| Low-end   | iPhone SE (2020)   | 798ms  |
| Mid-range | Google Pixel 7     | 423ms  |
| High-end  | Google Pixel 9     | 414ms  |
| High-end  | M3 Macbook         | 212ms  |

---

---
url: /guide/compliance.md
description: >-
  How Cap meets GDPR, CCPA and WCAG 2.2. The self-hosted, open-source CAPTCHA
  keeps user data on your servers, with no cookies, tracking, or third-party
  calls.
---

# Compliance

Cap is built privacy-first and self-hosted, which makes most regulatory questions simple to answer: **your users' data never leaves your infrastructure.** There are no cookies or tracking for end users, no third-party calls in the verification flow, and the proof-of-work runs entirely in the visitor's browser.

---

---
url: /guide/demo.md
description: >-
  Try Cap live: a working demo of the open-source, self-hosted CAPTCHA widget
  solving proof-of-work challenges in your browser, with no visual puzzles to
  click.
---

# Demo

---

---
url: /guide/server.md
---

# @cap.js/server

::: warning Legacy library — superseded by [`capjs-core`](./capjs-core.md)
`@cap.js/server` is no longer the recommended Cap server library. New projects should use [`capjs-core`](./capjs-core.md), which is stateless (no filesystem, no in-memory token list, works on Cloudflare Workers / Lambda / edge), uses signed JWTs, and is what [Cap Standalone](./standalone/index.md) is built on internally. See the [migration table](./capjs-core.md#how-it-differs-from-cap-js-server).
:::

`@cap.js/server` is Cap's server-side library for creating and validating challenges. Install it using your preferred package manager:

::: code-group

```bash [bun]
bun add @cap.js/server
```

```bash [npm]
npm i @cap.js/server
```

```bash [pnpm]
pnpm i @cap.js/server
```

:::

## Getting started

You'll need a database to store challenges and tokens. Here's an example using Bun's SQL module and a Postgres DB:

```js
import Cap from "@cap.js/server";
import { SQL } from "bun";

const db = new SQL(`postgres://user:password@localhost:5432/dbname`);

await db`
  CREATE TABLE IF NOT EXISTS challenges (
    token TEXT PRIMARY KEY,
    data JSONB NOT NULL,
    expires BIGINT NOT NULL
  );
`;

await db`
  CREATE TABLE IF NOT EXISTS tokens (
    key TEXT PRIMARY KEY,
    expires BIGINT NOT NULL
  );
`;

const cap = new Cap({
  storage: {
    challenges: {
      store: async (token, challengeData) => {
        await db`
          INSERT INTO challenges (token, data, expires)
          VALUES (${token}, ${challengeData}, ${challengeData.expires})
          ON CONFLICT (token)
          DO UPDATE SET
            data = EXCLUDED.data,
            expires = EXCLUDED.expires
        `;
      },

      read: async (token) => {
        const [row] = await db`
          SELECT data, expires
          FROM challenges
          WHERE token = ${token}
            AND expires > ${Date.now()}
          LIMIT 1
        `;

        return row ? { challenge: row.data, expires: Number(row.expires) } : null;
      },

      delete: async (token) => {
        await db`
          DELETE FROM challenges
          WHERE token = ${token}
        `;
      },

      deleteExpired: async () => {
        await db`
          DELETE FROM challenges
          WHERE expires <= ${Date.now()}
        `;
      },
    },

    tokens: {
      store: async (tokenKey, expires) => {
        await db`
          INSERT INTO tokens (key, expires)
          VALUES (${tokenKey}, ${expires})
          ON CONFLICT (key)
          DO UPDATE SET
            expires = EXCLUDED.expires
        `;
      },

      get: async (tokenKey) => {
        const [row] = await db`
          SELECT expires
          FROM tokens
          WHERE key = ${tokenKey}
            AND expires > ${Date.now()}
          LIMIT 1
        `;

        return row ? Number(row.expires) : null;
      },

      delete: async (tokenKey) => {
        await db`
          DELETE FROM tokens
          WHERE key = ${tokenKey}
        `;
      },

      deleteExpired: async () => {
        await db`
          DELETE FROM tokens
          WHERE expires <= ${Date.now()}
        `;
      },
    },
  },
});

export default cap;
```

Now, you can connect this to your backend to expose the routes needed for the widget:

::: code-group

```js [Elysia]
import { Elysia } from "elysia";
import cap from "./cap.js";

new Elysia()
  .post("/cap/challenge", async () => {
    return await cap.createChallenge();
  })
  .post("/cap/redeem", async ({ body, set }) => {
    const { token, solutions } = body;
    if (!token || !solutions) {
      set.status = 400;
      return { success: false };
    }
    return await cap.redeemChallenge({ token, solutions });
  })
  .listen(3000);
```

```js [Express]
import express from "express";
import cap from "./cap.js";

const app = express();
app.use(express.json());

app.post("/cap/challenge", async (req, res) => {
  res.json(await cap.createChallenge());
});

app.post("/cap/redeem", async (req, res) => {
  const { token, solutions } = req.body;
  if (!token || !solutions) {
    return res.status(400).json({ success: false });
  }
  res.json(await cap.redeemChallenge({ token, solutions }));
});

app.listen(3000);
```

```js [Fastify]
import Fastify from "fastify";
import cap from "../cap.js";

const fastify = Fastify();

fastify.post("/cap/challenge", async (req, res) => {
  res.send(await cap.createChallenge());
});

fastify.post("/cap/redeem", async (req, res) => {
  const { token, solutions } = req.body;
  if (!token || !solutions) {
    return res.code(400).send({ success: false });
  }
  res.send(await cap.redeemChallenge({ token, solutions }));
});

fastify.listen({ port: 3000 });
```

:::

In this example, the Cap API is at `/cap/` — set that in your widget as `data-cap-api-endpoint` ([see widget docs](./widget.md)).

When someone completes the CAPTCHA and sends the token back to your backend, you can validate the token and proceed with your logic.

```js
const { success } = await cap.validateToken("...");

if (!success) throw new Error("invalid cap token");

// ...your logic
```

## Methods and arguments

#### `new Cap({ ... })`

**Arguments**

```json
{
  "disableAutoCleanup": false,

  "storage": {
    "challenges": {
      "store": "async (token, challengeData) => {}",
      "read": "async (token) => {}",
      "delete": "async (token) => {}",
      "deleteExpired": "async () => {}"
    },
    "tokens": {
      "store": "async (tokenKey, expires) => {}",
      "get": "async (tokenKey) => {}",
      "delete": "async (tokenKey) => {}",
      "deleteExpired": "async () => {}"
    }
  },

  "state": {
    "challengesList": {},
    "tokensList": {}
  }

  // deprecated:

  // used for json keyval storage
  // "tokens_store_path": ".data/tokensList.json",

  // disables all filesystem operations, usually used alongside editing the state
  // "noFSState": false,
}
```

You can always access or set the options of the `Cap` class by accessing or modifying the `cap.config` object.

#### `await cap.createChallenge({ ... })`

**Arguments**

```json
{
  "challengeCount": 50,
  "challengeSize": 32,
  "challengeDifficulty": 4,
  "expiresMs": 600000
}
```

**Response:** `{ challenge, token, expires }`

#### `cap.redeemChallenge({ ... })`

```json
{
  token,
  solutions
}
```

**Response:** `{ success, token }`

#### `await cap.validateToken("...", { ... })`

**Arguments:**

```json
{
  "keepToken": false
}
```

**Response:** `{ success }`

#### `await cap.cleanup()`

Cleans up all expired challenges and tokens. This is usually done for you by default.

---

---
url: /about.md
description: >-
  Who builds Cap, the open-source, self-hosted CAPTCHA alternative: its
  maintainer, history, license, funding, and how to get in touch.
---

# About Cap

**TL;DR:** Cap is a free, open-source CAPTCHA alternative that replaces visual puzzles with proof-of-work and instrumentation challenges. It's licensed under Apache 2.0 and runs entirely on your own infrastructure, so visitor data never reaches a third party.

## What is Cap?

Cap is bot protection you can read, audit, and self-host:

* A **~20 KB widget** that renders a single checkbox instead of image puzzles.
* A **standalone server** that ships as one Docker container with a dashboard and multi-site-key support.
* **Server libraries** (`@cap.js/server` and community ports) for verifying challenges in your own backend.
* A **siteverify API compatible with reCAPTCHA and hCaptcha**, so migrating is mostly a URL swap.

The full source lives at [github.com/tiagozip/cap](https://github.com/tiagozip/cap) under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0).

## Why does Cap exist?

Mainstream CAPTCHAs either interrogate users with puzzles or profile them with fingerprinting and risk scores, and both approaches route your visitors' data through a vendor. Cap takes a different position:

* **Deterministic, not judgmental.** Every real user has a guaranteed path through; no classifier can silently reject someone for using a VPN or a privacy browser.
* **Self-hosted, not rented.** Verification happens on your servers, which makes GDPR and CCPA answers simple. See [Compliance](./guide/compliance.md).
* **Open, not promised.** Privacy claims are auditable because the code that makes decisions is public.

## Get in touch

* Bugs and feature requests: [GitHub issues](https://github.com/tiagozip/cap/issues)
* Security reports and everything else: <hi@tiago.zip>

---

---
url: /guide/middleware.md
description: >-
  Cap Checkpoints add a browser-check interstitial, like Cloudflare's, to block
  bots before they reach your site. Self-hosted, open-source proof-of-work
  CAPTCHA.
---

# About checkpoints

Cap's Checkpoints (previously known as middlewares) allow you to replicate Cloudflare's browser check interstitial. This helps prevent bots, LLMs and automated abuse from ever reaching your website.

They're extremely simple to set up and use, with you only having to add a few lines of code to your server, unlike moving your entire website over to Cloudflare. Note that this is kind of a nuclear solution, as it *will* also impact good bots such as search engine crawlers.

![Screenshot of Cap's checkpoint flow](/checkpoints_screenshot.webp)

---

---
url: /guide/middleware/elysia.md
description: >-
  Add a Cap Checkpoint to an Elysia app with the official middleware. Gate
  routes behind the self-hosted, open-source proof-of-work CAPTCHA in just a few
  lines.
---

# Elysia checkpoint

## Installation

```bash
bun add elysia @cap.js/middleware-elysia
```

> \[!NOTE] The template just needs to have a widget or hidden solver pointing at the `/__cap_clearance` URL. The sample template is [here](https://github.com/tiagozip/cap/blob/main/checkpoints/elysia/index.html).

## Usage

```javascript
import { Elysia, file } from "elysia";
import { capMiddleware } from "@cap.js/middleware-elysia";

new Elysia()
  .use(
    capMiddleware({
      token_validity_hours: 32, // how long the token is valid for
      tokens_store_path: ".data/tokensList.json",
      token_size: 16, // token size in bytes
      verification_template_path: join(dirname(fileURLToPath(import.meta.url)), "./index.html"),
      scoping: "scoped", // 'global' | 'scoped'
    }),
  )
  .get("/", () => "Hello Elysia!")
  .listen(3000);
```

That's it! You can now use the middleware to protect your routes.

---

---
url: /guide/middleware/express.md
description: >-
  Add a Cap Checkpoint to Express with @cap.js/checkpoint-express. Protect
  routes with the self-hosted, open-source proof-of-work CAPTCHA and a browser
  check.
---

# Express checkpoint

## Installation

```bash
bun add express cookie-parser @cap.js/checkpoint-express
```

## Usage

```javascript
import express from "express";
import cookieParser from "cookie-parser";
import path from "path";
import { dirname } from "path";
import { fileURLToPath } from "url";
import { capCheckpoint } from "@cap.js/checkpoint-express";

const app = express();
const __dirname = dirname(fileURLToPath(import.meta.url));

app.use(express.json());
app.use(cookieParser());

app.use(
  capCheckpoint({
    /*
      token_validity_hours: 32,
      tokens_store_path: ".data/tokensList.json",
      token_size: 16,
      verification_template_path: join(__dirname, "./index.html"),
    */
  }),
);

app.get("/", (req, res) => {
  res.sendFile(path.join(__dirname, "success.html"));
});

app.listen(3000, () => {
  console.log(`Server running on http://localhost:3000`);
});
```

That's it! You can now use the middleware to protect your routes.

---

---
url: /guide/middleware/hono.md
description: >-
  Add a Cap Checkpoint to a Hono app with @cap.js/checkpoint-hono. Protect
  routes with the self-hosted, open-source proof-of-work CAPTCHA and browser
  check.
---

# Hono checkpoint

## Installation

```bash
bun add hono @cap.js/checkpoint-hono
```

## Usage

```javascript
import { Hono } from "hono";
import { serveStatic } from "hono/bun";
import { capCheckpoint } from "@cap.js/checkpoint-hono";

const app = new Hono();

app.use(
  "*",
  capCheckpoint({
    token_validity_hours: 32, // how long the token is valid for
    tokens_store_path: ".data/tokensList.json",
    token_size: 16, // token size in bytes
    verification_template_path: join(dirname(fileURLToPath(import.meta.url)), "./index.html"),
  }),
);

app.get("/", (c) => c.text("Hello Hono!"));

export default app;
```

That's it! You can now use the middleware to protect your routes.

---

---
url: /guide/standalone/installation.md
---

# Installation

This section has moved to [Standalone](/guide/standalone/index.md).

---

---
url: /guide/standalone/usage.md
---

# Installation

This section has moved to [Standalone](/guide/standalone/index.md).

---

---
url: /guide/solver.md
description: >-
  @cap.js/solver solves Cap proof-of-work challenges server-side on Bun for
  machine-to-machine flows. A tiny, dependency-free piece of the open-source
  CAPTCHA.
---

# M2M

`@cap.js/solver` is a standalone library that can be used to solve Cap challenges from the server. It's extremely simple (no dependencies, one single file) yet as fast and efficient as the widget. Note that it can **only be used with Bun**.

This package does not bypass any actual proof-of-work. **It does not support instrumentation challenges.**

## Installation

```bash
bun add @cap.js/solver
```

## Usage

#### From seeded challenges

```js
import solver from "@cap.js/solver";

console.log(
  await solver("challenge token", {
    c: 50, // challenge count
    s: 32, // salt size
    d: 4, // difficulty
  }),
);
```

#### From challenge list

```js
import solver from "@cap.js/solver";

const challenges = [
  ["a5b6fda4aaed97cf61d7dd9259f733b5", "d455"],
  ["286bcc39249f9ee698314b600c32e40f", "f0ff"],
  ["501350aa7c46573cb604284554045703", "4971"],
  ["a55c02f3b9b4cd088a5a7ee3d4941c14", "eab7"],
  ["5f3362c12e2779f56f4ef75b4494f5e6", "999f"],
  /* ... */
];

console.log(await solver(challenges));
```

**Output:**

```json
[67302, 64511, 40440, 27959, 71259 /* ... */]
```

The 2nd argument is optional but can always be provided. It's always an object.

* For **all challenge types**, `workerCount` indicates the number of workers to use (default is the number of CPU cores).

* For **all challenge types**, `onProgress` can also be used to provide a callback for progress updates.

* For **seeded challenges only**, it is used to specify the number of solutions to generate, the size of the challenges, and the difficulty

---

---
url: /guide/troubleshooting/instrumentation.md
description: >-
  Troubleshooting Cap verification failures: fixes for the open-source,
  self-hosted CAPTCHA when proof-of-work or instrumentation checks fail in your
  browser.
---

# Troubleshooting

This verification can fail for various reasons, not solely due to bot activity. If you're having trouble completing verification, follow these steps to resolve the issue.

## 1. Try incognito or private mode

Open your browser's incognito or private mode to rule out issues caused by extensions or cached data.

* **Chrome / Edge:** Press `Ctrl+Shift+N` (Windows) or `Cmd+Shift+N` (Mac)
* **Firefox:** Press `Ctrl+Shift+P` (Windows) or `Cmd+Shift+P` (Mac)
* **Safari:** Go to **File → New Private Window**

## 2. Disable your browser extensions

Some extensions may interfere with the verification process. Try disabling them temporarily:

1. Open your browser's extensions or add-ons settings
2. Temporarily disable **all** extensions
3. Reload the page and try again

If this fixes the issue, re-enable extensions one by one to find the culprit.

## 3. Try a different browser or device

The issue may be specific to your current browser. Switch to another browser or device to test.

* Try **Chrome**, **Firefox**, **Edge**, or **Safari**
* Note: **Internet Explorer is not supported**. Use a modern browser instead
* If possible, try on a completely different device (e.g., your phone)

## 4. Update your browser

An outdated browser can cause verification to fail.

1. Open your browser's menu
2. Go to **Help → About** (or similar)
3. Install any available updates and restart your browser

## 5. Switch to a different network

Your current network may have restrictions that interfere with verification.

* Connect to a **different Wi-Fi network**
* Try using a **mobile hotspot** from your phone
* If you're on a corporate or school network, those often have strict filtering that can block verification

## 6. Close any automated browser sessions

If you're using a browser controlled by automation software (such as Selenium, Puppeteer, or Playwright), verification will be blocked.

1. **Fully close** the automated browser session
2. Open the page in a **regular, manually-operated browser**
3. Complete the verification there

AI agent browsers are also blocked — make sure you're using a standard browser.

***

If you've tried all of the above and still can't get through, consider reaching out to the site owner for further assistance. You may also alternatively [file an issue](https://github.com/tiagozip/cap/issues).