Skip to main content
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: 
pip install humancheck
Or install from source: 
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

pip install humancheck

​
2. Initialize Configuration

humancheck init
This creates a humancheck.yaml configuration file.

​
3. Start the Services

humancheck start
This launches:

​
4. Make Your First Request

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: 
# 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

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

Docker

Deploy using Docker containers

Kubernetes

Deploy on Kubernetes clusters

Cloud VMs

Deploy on AWS, GCP, Azure VMs

On-Premise

Deploy on your own infrastructure

​
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

FeatureOpen SourcePlatform
Core Features✅ All core HITL features✅ All core HITL features
Base URLYour own domainhttps://api.humancheck.dev
SetupSelf-hostedManaged cloud
DatabaseYou manageManaged
UpdatesManualAutomatic
Multi-tenancy❌✅ Organizations, Users, Teams
RoutingConfig-based (YAML)UI-based with prioritization & ACL
ConnectorsBasic (Slack, Email, Webhook)Dozens of built-in connectors (instant setup)
No-Code Integrations❌✅ n8n, Zapier, Gumloop, etc.
Multi-User Approval❌✅ Complex approval workflows
WebhooksBasic✅ Advanced webhook system
Evals❌✅ Evaluation framework
OAuth Connectors❌✅ Built-in OAuth
Audit Logs❌✅ Complete audit trail
SupportCommunityPriority support
CostFree (self-hosted)Paid plans
CustomizationFull controlLimited
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.

​
Configuration

Configure routing and reviewers in humancheck.yaml: 
# Default reviewers
default_reviewers:
  - [email protected]
  - [email protected]

# Routing rules
routing_rules:
  - name: "High-value payments"
    priority: 10
    conditions:
      task_type: {"operator": "=", "value": "payment"}
      metadata.amount: {"operator": ">", "value": 10000}
    assign_to: "[email protected]"
    is_active: true

​
Next Steps