---
outline: [2, 3]
description: "Set up Cap, the open-source self-hosted CAPTCHA, in about five minutes. Run the server with Docker or inside your own backend, add the widget, verify tokens. No Google, no telemetry, no visual puzzles."
---
# Quickstart
Cap has two parts: a widget, which runs and solves challenges in the visitor's browser and gives you a token; and the server (capd), which issues challenges and verifies those tokens.
## 1. Set up capd
First, you'll need to set up capd. It runs as a self-hosted server with a dashboard, analytics, rules, and an API. Keys and settings are stored in Valkey. Before you start, you'll need to make two choices:
**1. Where to run capd:** You can run it on your own server with Docker, use [Railway](https://railway.com/deploy/cap-1?referralCode=93HYBZ&utm_medium=integration&utm_source=template&utm_campaign=generic), or use a serverless platform like [Workers](./capd/workers.md). This guide uses Docker.
**2. Where to store analytics:** You can use DuckDB (lightweight, best for small websites) or ClickHouse (more scalable). Both are easy to set up and built-in.
::: code-group
```bash [DuckDB]
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.duckdb.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -d
```
```bash [ClickHouse]
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -d
```
:::
Open `http://localhost:3000` and log in with the `ADMIN_KEY` from `.env`, which is the dashboard password. Create a site key and copy both the site key and its secret.
The widget talks to this server from your visitors' browsers, so in production it needs a public URL. We recommend using something like [Tunnels](https://developers.cloudflare.com/tunnel/), but [the capd docs](./capd/index.md) cover most other cases, including reverse proxies.
## 2. Add the widget
Load the script, pinning a version from the [releases page](https://github.com/tiagozip/cap/releases):
```html
```
Put the widget inside your form:
```html
```
The endpoint is `https:////`.
When the visitor solves it, the widget adds a hidden `cap-token` field to the form. Outside a form, listen for the `solve` event instead:
```js
document.querySelector("cap-widget").addEventListener("solve", (e) => {
const token = e.detail.token;
});
```
The [widget page](./widget.md) has snippets for React, Vue, Svelte and other frameworks.
## 3. Verify the token
Before you trust a submission, send its token to `/siteverify` from your server:
::: code-group
```js [fetch]
const res = await fetch("https://cap.example.com//siteverify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ secret: "", response: token }),
});
const { success } = await res.json();
```
```py [python]
import requests
success = requests.post(
"https://cap.example.com//siteverify",
json={"secret": "", "response": token},
).json()["success"]
```
```php [php]
$res = file_get_contents("https://cap.example.com//siteverify", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Content-Type: application/json",
"content" => json_encode(["secret" => "", "response" => $token]),
],
]));
$success = json_decode($res, true)["success"] ?? false;
```
```sh [curl]
curl -X POST "https://cap.example.com//siteverify" \
-H "Content-Type: application/json" \
-d '{"secret": "", "response": ""}'
```
:::
`` is the site key's secret, not your `ADMIN_KEY`. Mixing the two up is the most common setup mistake.
If you're moving from reCAPTCHA, `/siteverify` takes the same request format, so your verification code only needs your server's hostname.
A valid token returns `{ "success": true }`. Each token works once, so a second verification of the same token fails. Sending it twice is a quick way to check the setup end to end.
## Using the core library instead
If you'd rather issue and check challenges inside your own backend, the [core library](./capjs-core.md) is a minimal npm package that does only that. You store tokens in your own database, and you don't get the dashboard, analytics or rate limiting.
## Next steps
- [Customize the widget](./widget.md#attributes): its labels, language and styling
- [Configure capd](./capd/options.md): proxies, widget files and the API
- Read the [core library reference](./capjs-core.md)
- Read [how Cap works](./workings.md)