Skip to content
HiveGuard

Quick Start

This guide gets HiveGuard running locally, uploads a small dataset, and confirms that labels are being collected.

Prerequisites

  • Docker + Docker Compose
  • Python 3.11+ (for the CLI)
  • A small dataset to label (a few image URLs, text snippets, or audio clips)

1. Clone and configure

Terminal window
git clone https://github.com/your-org/hiveguard
cd hiveguard
cp .env.example .env

Edit .env:

Terminal window
TARGET_URL=http://httpbin.org/anything   # the service to sit in front of
SECRET_KEY=change-me-in-production
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=changeme

TARGET_URL is whatever application you want HiveGuard in front of. It just needs to be an HTTP service that gets real (or test) traffic. The labeling happens on the way in.

2. Start the stack

Terminal window
docker compose up --build -d

HiveGuard starts on port 8000. Check it’s up:

Terminal window
curl http://localhost:8000/api/v1/health
# {"status":"ok","version":"0.2.0"}

3. Install the CLI

Terminal window
pip install hiveguard-cli
# or from the repo:
uv pip install -e apps/cli

Configure it to point at your local instance:

Terminal window
hiveguard auth configure
# Base URL [http://localhost:8000]:
# Dashboard username: admin
# Dashboard password: changeme

4. Create an API key

Terminal window
hiveguard keys create my-first-key
# Raw key (store this — shown once): hg_xxxxxxxxxxxxxxxx
Terminal window
export HIVEGUARD_API_KEY=hg_xxxxxxxxxxxxxxxx

5. Create a dataset and upload items

A dataset groups items of the same type. Create one first:

Terminal window
hiveguard datasets create "My Images" --modality image
# id: 00000000-0000-0000-0000-000000000001

Then prepare a JSONL file of items to label:

{"dataset_id": "00000000-0000-0000-0000-000000000001", "data_ref": "https://example.com/img1.jpg", "modality": "image"}
{"dataset_id": "00000000-0000-0000-0000-000000000001", "data_ref": "https://example.com/img2.jpg", "modality": "image"}
{"dataset_id": "00000000-0000-0000-0000-000000000001", "data_ref": "https://example.com/img3.jpg", "modality": "image"}

Upload them:

Terminal window
hiveguard items upload items.jsonl
# Uploading 3 items... ✓ 3 created

6. See a challenge

This is what a visitor experiences. When HiveGuard intercepts a request, it generates a challenge from your dataset:

Terminal window
curl -H "X-HiveGuard-Key: $HIVEGUARD_API_KEY" \
     http://localhost:8000/api/v1/challenge/generate

You’ll get back a JSON challenge containing one of your items. That’s the labeling task — the visitor answers it, and their answer flows into the consensus engine.

7. Check the dashboard

Open http://localhost:8000/dashboard in your browser (admin / changeme).

The Datasets tab shows your uploaded items. The Metrics tab shows how many challenges have been served and how many labels are in progress. As traffic flows through, Labeled shows finalized labels ready for export.

What’s next