📚 Documentation

🏁 Getting Started

OpenSentry is a complete security camera system that runs entirely on your local network. Get up and running in under 5 minutes.

Quick Installation

# 1. Clone the Command Center
git clone https://github.com/SourceBox-LLC/OpenSentry-Command.git
cd OpenSentry-Command

# 2. Run setup
chmod +x setup.sh && ./setup.sh

# 3. Access dashboard at https://localhost:5000

What You Get

💻 System Requirements

Command Center

Camera Nodes

📦 Installation Guide

Prerequisites

Install Docker

# Linux
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in

# macOS
# Download Docker Desktop from docker.com

# Windows
# Install WSL2 first, then Docker Desktop

Command Center Setup

1. Clone the repository
   Copy

   git clone https://github.com/SourceBox-LLC/OpenSentry-Command.git
   cd OpenSentry-Command

2. Run the setup script
   Copy

   chmod +x setup.sh && ./setup.sh

3. Create your admin account

   The setup wizard will prompt you for:

   • Username (default: admin)
   • Password (minimum 8 characters)
4. Access the dashboard

   Open your browser and navigate to:

   https://localhost:5000

📷 Adding Your First Camera

Step 1: Get Your Security Secret

1. Log into the Command Center
2. Click the ⚙️ Settings icon (top right)
3. Copy your Security Secret

Step 2: Set Up a Camera Node

Choose the node type that fits your needs:

Option A: Basic Camera Node

# Simple streaming camera
git clone https://github.com/SourceBox-LLC/OpenSentry-Node.git
cd OpenSentry-Node
chmod +x setup.sh && ./setup.sh

Option B: Motion Detection Node

# Streaming + motion detection alerts
git clone https://github.com/SourceBox-LLC/OpenSentry-MotionNode.git
cd OpenSentry-MotionNode
chmod +x setup.sh && ./setup.sh

Option C: Face Detection Node

# Streaming + real-time face detection
git clone https://github.com/SourceBox-LLC/OpenSentry-FaceDetectionNode.git
cd OpenSentry-FaceDetectionNode
chmod +x setup.sh && ./setup.sh

Option D: Object Detection Node

# Streaming + AI object detection (people, vehicles, animals, etc.)
git clone https://github.com/SourceBox-LLC/OpenSentry-ObjectDetectionNode.git
cd OpenSentry-ObjectDetectionNode
chmod +x setup.sh && ./setup.sh

Step 3: Configure the Node

During setup, you'll be asked for:

• Camera name: e.g., "Front Door", "Backyard"
• Camera device: Usually /dev/video0
• Security secret: Paste the secret from Step 1

🎛️ Command Center

The Command Center is your central hub for managing all cameras, users, and settings.

Dashboard Features

Camera Management

Camera Controls

Status Indicators

User Management

Admins can create and manage user accounts from Settings → Manage Users.

User Roles

📹 Camera Nodes

Camera nodes are individual devices that capture and stream video to the Command Center.

Node Types Comparison

Node Type Details

📷 Basic Node

Simple camera streaming without any detection. Lowest resource usage, ideal for basic monitoring.

🎯 Motion Detection Node

Detects movement using frame differencing. Great for security alerts when any motion occurs.

📸 Face Detection Node

Uses OpenCV DNN with ResNet-10 SSD model to detect human faces in real-time. Publishes events with confidence scores when faces are detected or leave the frame.

🔍 Object Detection Node

AI-powered detection using YOLOv4. Identifies 80+ object types including people, vehicles, animals, and household items. Choose between:

• Full model: Best accuracy (~65% mAP), slower (~2-5 DPS), ~1.5GB RAM
• Tiny model: Fast (~15-30 DPS), lower accuracy (~40% mAP), ~512MB RAM
• Auto: Tries full first, falls back to tiny if insufficient memory

Configuration

Camera nodes are configured via environment variables in the .env file:

# Camera Settings
CAMERA_NAME=Front Door
CAMERA_DEVICE=/dev/video0
CAMERA_ID=front-door

# Security
OPENSENTRY_SECRET=your-secret-key

# Network
COMMAND_CENTER_HOST=localhost

Common Commands

# View logs
docker logs opensentry-node-<camera-id> -f

# Restart node
docker restart opensentry-node-<camera-id>

# Stop node
docker stop opensentry-node-<camera-id>

# Remove node
docker rm -f opensentry-node-<camera-id>

🎯 Motion Detection

OpenSentry's motion detection uses OpenCV to analyze video frames in real-time and alert you to any movement.

How It Works

1. Frame Analysis: OpenCV compares consecutive video frames
2. Motion Detection: Identifies areas with significant pixel changes
3. Event Publishing: Sends JSON events via MQTT to Command Center
4. Visual Feedback: Shows red bounding box around motion
5. Notifications: Triggers alerts in the dashboard

Motion Event Format

{
  "event": "motion_start",
  "timestamp": 1234567890,
  "area_x": 100,
  "area_y": 200,
  "area_width": 300,
  "area_height": 400
}

Sensitivity Tuning

Adjust these parameters in your motion node's configuration:

Recommended Settings

Motion Features in Dashboard

• Real-time Alerts: Red "MOTION DETECTED!" badge on video feed
• Visual Effects: Camera card pulses with red glow during motion
• Toast Notifications: Pop-up alerts (configurable)
• Motion History: Last 100 events stored per camera
• History Button: Click to view recent motion events with timestamps

📸 Face Detection

OpenSentry's Face Detection Node uses OpenCV DNN with a ResNet-10 SSD model for real-time face detection.

How It Works

1. DNN Processing: Each frame is analyzed by the neural network
2. Face Detection: Identifies human faces with confidence scores
3. Event Publishing: Sends JSON events via MQTT when faces appear/disappear
4. Visual Feedback: Shows magenta bounding boxes around detected faces
5. Notifications: Triggers alerts in the dashboard

Face Event Format

Face detected:

{
  "event": "face_detected",
  "timestamp": 1705847293,
  "count": 2,
  "max_confidence": 0.95
}

Face ended:

{
  "event": "face_end",
  "timestamp": 1705847298,
  "duration": 5
}

Configuration

Face Detection Features in Dashboard

• Real-time Alerts: Purple "FACE DETECTED" badge on video feed
• Visual Effects: Camera card pulses with purple glow during detection
• Toast Notifications: Pop-up alerts (configurable in Settings)
• Face History: Last 100 events stored per camera
• History Button: Click to view recent face events with timestamps

🔍 Object Detection

OpenSentry's Object Detection Node uses YOLOv4 to identify 80+ object types in real-time.

Supported Objects (COCO 80 Classes)

Detection Models

DPS = Detections Per Second (shown in video overlay)

Object Event Format

Objects detected:

{
  "event": "objects_detected",
  "objects": [
    {"class": "person", "confidence": 85},
    {"class": "dog", "confidence": 72}
  ]
}

Objects cleared:

{
  "event": "objects_cleared",
  "objects": []
}

Configuration

Object Detection Features in Dashboard

• Real-time Alerts: Cyan "OBJECTS" badge on video feed
• Visual Effects: Camera card pulses with cyan glow during detection
• Toast Notifications: Pop-up alerts (configurable in Settings)
• Object History: Last 100 events stored per camera
• History Button: Click to view recent object detections

Performance Tips

• Use tiny model on Raspberry Pi 4 for better performance
• Use full model on desktop/server with 4GB+ RAM for best accuracy
• Lower confidence threshold (0.15-0.20) detects more objects but may have false positives
• Higher confidence threshold (0.40+) reduces false positives but may miss objects

⚙️ Environment Variables

Command Center (.env)

# Authentication
OPENSENTRY_USERNAME=admin
OPENSENTRY_PASSWORD=your-password

# Security
OPENSENTRY_SECRET=your-secret-key

# Session
SESSION_TIMEOUT=30  # minutes

# HTTPS
HTTPS_ENABLED=true

# MQTT
MQTT_PORT=1883
MQTT_USE_TLS=false

Camera Node (.env)

# Camera
CAMERA_NAME=Front Door
CAMERA_DEVICE=/dev/video0
CAMERA_ID=front-door

# Security
OPENSENTRY_SECRET=your-secret-key

# Network
COMMAND_CENTER_HOST=localhost

# Motion Detection (Motion Node only)
MOTION_THRESHOLD=25
MOTION_MIN_AREA=500
MOTION_COOLDOWN=2

🔐 Security Configuration

Encryption Protocols

Security Secret

The OPENSENTRY_SECRET is used to:

• Authenticate camera nodes with Command Center
• Derive RTSP and MQTT credentials
• Encrypt sensitive data

Certificate Management

SSL certificates are automatically generated on first run. To trust them:

Browser Trust

• Chrome/Edge: Accept certificate on first visit
• Firefox: Click "Advanced" → "Accept the Risk"
• Safari: Click "Show Details" → "Visit Website"

System Trust (Optional)

# Linux
sudo cp certs/ca.crt /usr/local/share/ca-certificates/opensentry-ca.crt
sudo update-ca-certificates

# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain certs/ca.crt

🌐 Network Configuration

Service Discovery

OpenSentry uses mDNS (Multicast DNS) for automatic camera discovery:

• Cameras broadcast their presence on the network
• Command Center automatically detects new cameras
• No manual IP configuration required

Firewall Rules

If using a firewall, allow these ports:

Docker Networking

OpenSentry uses host networking mode by default:

network_mode: host

This ensures:

• mDNS discovery works properly
• No port mapping required
• Direct network access for streams

🔔 Notifications

Notification Types

• Motion Alerts: When motion is detected by camera
• Camera Status: When camera goes online/offline
• System Events: User login, configuration changes

Configuration

Configure notifications in the Command Center:

1. Click ⚙️ Settings
2. Go to Notifications section
3. Toggle settings:
   • Motion Detection Alerts: Enable/disable motion notifications
   • Toast Notifications: Show/hide pop-up alerts

🎬 Recording

OpenSentry supports both manual and automatic video recording from all camera types.

Recording Methods

Auto-Recording Configuration

Configure automatic recording in Settings → Recording:

24/7 Continuous Recording

Enable 24/7 recording for complete surveillance coverage:

• Master Toggle: Overrides all individual auto-recording settings
• All Cameras: Records from every connected camera simultaneously
• Simple Control: One toggle to start/stop all recording

Media Library

Access saved recordings from the Media Library:

1. Click the 📁 Media Library icon (top right)
2. Switch between Snapshots and Recordings tabs
3. Click Play to watch in browser
4. Click Download to save locally

Video Format

All recordings are transcoded to H.264 format for browser compatibility:

• Format: MP4 with H.264 video codec
• Storage: Encrypted binary blobs in SQLite database
• Playback: Direct browser playback or download

Recording Controls

🔌 API Reference

OpenSentry provides a REST API for integration with external applications.

Authentication

All API endpoints require authentication. Use session cookies after login.

Endpoints

GET /api/cameras

List all cameras with their current status and motion data.

curl -k https://localhost:5000/api/cameras \
  -H "Cookie: session=your-session-cookie"

Response:

{
  "camera-id": {
    "name": "Front Door",
    "status": "streaming",
    "node_type": "motion",
    "capabilities": "streaming,motion_detection",
    "motion_active": false,
    "motion_events": [...],
    "last_seen": 1234567890
  }
}

GET /api/camera/{id}/status

Get status of a specific camera.

POST /api/camera/{id}/command

Send command to a camera.

curl -k -X POST https://localhost:5000/api/camera/front-door/command \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{"command": "start"}'

Available Commands:

• start - Start streaming
• stop - Stop streaming
• shutdown - Shut down camera node

DELETE /api/camera/{id}/forget

Remove a camera from the system.

POST /api/regenerate-secret

Generate a new security secret (admin only).

🤖 AI Integration

OpenSentry provides an MCP (Model Context Protocol) server for integrating with AI assistants like OpenCode and Claude Code.

MCP Server

The MCP server enables AI assistants to query camera status, detection alerts with location data, and system health through a standardized interface.

Features

• List cameras and check status
• Query detection alerts with motion region/bounding box data
• Motion hotspot analysis (heatmap of detection locations)
• Activity timeline (detection patterns over time)
• Access recordings and snapshots
• Check system health and view settings

Installation

git clone https://github.com/SourceBox-LLC/OpenSentry-MCP.git
cd OpenSentry-MCP
./setup.sh

Configuration

Create a `.env` file or set environment variables:

OPENSENTRY_URL=https://localhost:5000
OPENSENTRY_USERNAME=admin
OPENSENTRY_PASSWORD=your_password

Available Tools

OpenCode Configuration

{
  "mcp": {
    "opensentry": {
      "type": "local",
      "command": ["uv", "--directory", "/path/to/OpenSentry-MCP", "run", "python", "-m", "opensentry_mcp"],
      "enabled": true,
      "environment": {
        "OPENSENTRY_URL": "https://localhost:5000",
        "OPENSENTRY_USERNAME": "admin",
        "OPENSENTRY_PASSWORD": "your_password"
      }
    }
  }
}

Example Queries

• "What cameras do I have and which are online?"
• "Show me motion alerts from the last 24 hours"
• "Where in the frame was motion detected?"
• "Show me a heatmap of where motion is occurring"
• "What are the busiest times of day for activity?"

📡 MQTT Protocol

MQTT is used for real-time communication between nodes and Command Center.

Topics

Message Formats

Status Message

{
  "status": "streaming",
  "node_type": "motion",
  "capabilities": "streaming,motion_detection",
  "timestamp": 1234567890
}

Motion Event

{
  "event": "motion_start",
  "timestamp": 1234567890,
  "area_x": 100,
  "area_y": 200,
  "area_width": 300,
  "area_height": 400
}

Commands

start
stop
shutdown

🌍 Remote Access

Access your cameras from anywhere using Tailscale VPN.

Why Tailscale?

• Free for personal use (up to 100 devices)
• No port forwarding required
• End-to-end encrypted (WireGuard)
• Works behind any firewall/NAT
• Your server stays hidden from public internet

Setup Guide

1. Install Tailscale on Server

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

2. Install on Your Devices

Download Tailscale for your devices:

• Download Tailscale
• Sign in with the same account

3. Get Your Server's Tailscale IP

tailscale ip -4
# Example output: 100.64.0.1

4. Access from Anywhere

https://YOUR_TAILSCALE_IP:5000

🍓 Raspberry Pi Setup

Raspberry Pi is perfect for camera nodes - affordable, low-power, and reliable.

Compatibility

Installation

1. Install Raspberry Pi OS

• Use Raspberry Pi Imager
• Choose "Raspberry Pi OS Lite (64-bit)"
• Enable SSH in settings

2. SSH into Your Pi

ssh pi@raspberrypi.local

3. Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker pi
sudo reboot

4. Install Camera Node

# Basic node (streaming only)
git clone https://github.com/SourceBox-LLC/OpenSentry-Node.git
cd OpenSentry-Node

# Motion detection node
git clone https://github.com/SourceBox-LLC/OpenSentry-MotionNode.git
cd OpenSentry-MotionNode

# Face detection node
git clone https://github.com/SourceBox-LLC/OpenSentry-FaceDetectionNode.git
cd OpenSentry-FaceDetectionNode

# Object detection node (YOLOv4)
git clone https://github.com/SourceBox-LLC/OpenSentry-ObjectDetectionNode.git
cd OpenSentry-ObjectDetectionNode

# Run setup (for whichever node you chose)
chmod +x setup.sh && ./setup.sh

Performance Tips

• Use wired Ethernet for best streaming quality
• Use a heatsink/fan for Pi 4/5 with motion detection
• Reduce resolution if experiencing lag
• Use a quality power supply (3A for Pi 4/5)

🔧 Troubleshooting

Common Issues

Camera Not Appearing in Dashboard

• Ensure both devices are on the same network
• Check that security secrets match
• Wait 30 seconds for auto-discovery
• Check camera node logs: docker logs opensentry-node-{id}

No Video Feed

• Click "Start" button on camera card
• Check camera is plugged in: ls /dev/video*
• Try different camera device: CAMERA_DEVICE=/dev/video1

Motion Not Detected

• Ensure using Motion Node (not Basic Node)
• Check MQTT connection in logs
• Adjust sensitivity: lower MOTION_THRESHOLD value
• Ensure adequate lighting

Too Many False Positives

• Increase MOTION_THRESHOLD (30-35)
• Increase MOTION_MIN_AREA (1000+)
• Add MOTION_COOLDOWN time
• Check for environmental factors (shadows, reflections)

Can't Login

• Default credentials: admin / opensentry
• Check .env file for custom credentials
• Wait 5 minutes if account locked

Port Already in Use

• Stop other services on port 5000
• Or change port in docker-compose.yml

Debug Commands

# View Command Center logs
docker logs opensentry-command-center -f

# View camera node logs
docker logs opensentry-node-{camera-id} -f

# Check Docker containers
docker ps

# Test camera device
ffmpeg -f v4l2 -i /dev/video0 -frames 1 test.jpg

# Check network
ip addr show

# Check mDNS
avahi-browse -a

❓ Frequently Asked Questions

Is OpenSentry really free?

Yes! OpenSentry is 100% open source under the MIT license. Free for personal and commercial use.

Does it require internet?

No. OpenSentry runs entirely on your local network. Internet is only needed for initial Docker image downloads.

How many cameras can I add?

Unlimited! Performance depends on your hardware. A typical PC can handle 10-20 cameras easily.

Can I use IP cameras?

Currently, OpenSentry supports USB webcams. IP camera support is on the roadmap.

Is the video encrypted?

Yes! All video streams use RTSPS (RTSP over TLS) encryption.

Can I record video?

Yes! OpenSentry supports multiple recording modes:

• Manual: Click Record button to start/stop
• Auto-Recording: Record on motion, face, or object detection
• 24/7: Continuous recording from all cameras

All recordings are stored in the encrypted database and playable in the browser.

Does it work on Windows?

Yes, using WSL2 (Windows Subsystem for Linux). See the installation guide for details.

Can I access cameras remotely?

Yes! Use Tailscale VPN for secure remote access. See the Remote Access section.

What's the difference between node types?

OpenSentry offers 4 node types:

• Basic: Simple streaming, lowest resource usage
• Motion: Streaming + motion detection alerts
• Face Detection: Streaming + real-time face detection with confidence scores
• Object Detection: Streaming + AI-powered detection of 80+ objects (people, vehicles, animals, etc.) using YOLOv4

How do I update OpenSentry?

git pull
docker-compose down
docker-compose up -d --build