> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humancheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Humancheck Open Source

> Self-host the Humancheck stack for full control

Humancheck Open Source is the core package that you can self-host for complete control over your data, deployment, and customization.

## Installation

Install the core package:

```bash theme={null}
pip install humancheck
```

Or install from source:

```bash theme={null}
git clone https://github.com/humancheck/humancheck.git
cd humancheck
poetry install
```

## Base URL

When self-hosting, use your own base URL:

```
http://localhost:8000  # Local development
https://your-domain.com  # Production deployment
```

## Features

### Core HITL Functionality

* ✅ **Review Management**: Create, track, and manage review requests
* ✅ **Decision Making**: Approve, reject, or modify actions
* ✅ **Feedback System**: Rate and comment on reviews
* ✅ **Attachments**: Upload and preview files (images, documents, code)
* ✅ **Framework Adapters**: REST API, MCP, LangChain, Mastra
* ✅ **Basic Routing**: Simple config-based routing rules (YAML)
* ✅ **Connectors**: Slack, Email, Webhook notifications
* ✅ **Dashboard**: Streamlit-based review interface
* ✅ **Statistics**: Basic review analytics

### Self-Hosted Benefits

* **Full Control**: Complete control over data and deployment
* **Customizable**: Modify and extend as needed
* **Open Source**: MIT licensed
* **No Vendor Lock-in**: Your data, your infrastructure

## Getting Started

### 1. Install

```bash theme={null}
pip install humancheck
```

### 2. Initialize Configuration

```bash theme={null}
humancheck init
```

This creates a `humancheck.yaml` configuration file.

### 3. Start the Services

```bash theme={null}
humancheck start
```

This launches:

* **API Server**: [http://localhost:8000](http://localhost:8000)
* **Dashboard**: [http://localhost:8501](http://localhost:8501)

### 4. Make Your First Request

```python theme={null}
import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8000/reviews",  # Your self-hosted URL
        json={
            "task_type": "payment",
            "proposed_action": "Process payment of $5,000",
            "agent_reasoning": "High-value payment requires approval",
            "confidence_score": 0.85,
            "urgency": "high"
        }
    )
    review = response.json()
    print(f"Review ID: {review['id']}")
```

## Configuration

Edit `humancheck.yaml` to customize:

```yaml theme={null}
# API Server Configuration
api_host: 0.0.0.0
api_port: 8000

# Dashboard Configuration
streamlit_host: 0.0.0.0
streamlit_port: 8501

# Database Configuration
storage: sqlite  # or postgresql
db_path: ./humancheck.db

# Authentication (optional)
enable_auth: false
api_key: null
```

## Deployment

### Docker Deployment

```bash theme={null}
docker run -p 8000:8000 -p 8501:8501 humancheck/humancheck
```

### Production Deployment

For production, we recommend:

1. **Use PostgreSQL** instead of SQLite
2. **Enable authentication** with API keys
3. **Set up reverse proxy** (nginx, Traefik, etc.)
4. **Configure SSL/TLS** certificates
5. **Set up monitoring** and logging

## Self-Hosting Options

<CardGroup cols={2}>
  <Card title="Docker" icon="docker">
    Deploy using Docker containers
  </Card>

  <Card title="Kubernetes" icon="kubernetes">
    Deploy on Kubernetes clusters
  </Card>

  <Card title="Cloud VMs" icon="server">
    Deploy on AWS, GCP, Azure VMs
  </Card>

  <Card title="On-Premise" icon="building">
    Deploy on your own infrastructure
  </Card>
</CardGroup>

## Customization

Since you're self-hosting, you can:

* Modify the source code
* Add custom adapters
* Create custom connectors
* Extend the dashboard
* Add custom routing logic
* Integrate with your auth system

## Differences from Platform

| Feature                  | Open Source                   | Platform                                      |
| ------------------------ | ----------------------------- | --------------------------------------------- |
| **Core Features**        | ✅ All core HITL features      | ✅ All core HITL features                      |
| **Base URL**             | Your own domain               | `https://api.humancheck.dev`                  |
| **Setup**                | Self-hosted                   | Managed cloud                                 |
| **Database**             | You manage                    | Managed                                       |
| **Updates**              | Manual                        | Automatic                                     |
| **Multi-tenancy**        | ❌                             | ✅ Organizations, Users, Teams                 |
| **Routing**              | Config-based (YAML)           | UI-based with prioritization & ACL            |
| **Connectors**           | Basic (Slack, Email, Webhook) | Dozens of built-in connectors (instant setup) |
| **No-Code Integrations** | ❌                             | ✅ n8n, Zapier, Gumloop, etc.                  |
| **Multi-User Approval**  | ❌                             | ✅ Complex approval workflows                  |
| **Webhooks**             | Basic                         | ✅ Advanced webhook system                     |
| **Evals**                | ❌                             | ✅ Evaluation framework                        |
| **OAuth Connectors**     | ❌                             | ✅ Built-in OAuth                              |
| **Audit Logs**           | ❌                             | ✅ Complete audit trail                        |
| **Support**              | Community                     | Priority support                              |
| **Cost**                 | Free (self-hosted)            | Paid plans                                    |
| **Customization**        | Full control                  | Limited                                       |

<Note>
  For advanced features like multi-tenancy, organizations, teams, dozens of built-in connectors, no-code integrations (n8n, Zapier, Gumloop), multi-user approval workflows, advanced webhooks, evals, and OAuth connectors, check out [Humancheck Platform](/platform/overview).
</Note>

## Configuration

Configure routing and reviewers in `humancheck.yaml`:

```yaml theme={null}
# Default reviewers
default_reviewers:
  - alice@example.com
  - bob@example.com

# Routing rules
routing_rules:
  - name: "High-value payments"
    priority: 10
    conditions:
      task_type: {"operator": "=", "value": "payment"}
      metadata.amount: {"operator": ">", "value": 10000}
    assign_to: "finance@example.com"
    is_active: true
```

## Next Steps

* Check out the [Quickstart Guide](/quickstart#open-source-quickstart)
* Learn about [Configuration](/configuration/settings)
* Explore [Integrations](/integrations/rest-api)
* Review [Contributing Guide](/contributing)