capture

capture

Docker app from LubricantJam's Repository

Capture - An open source hardware monitoring agent for Checkmate.

Requirements

You will need to configure the Checkmate web panel along-side this container. This is a reporting agent only.
Overview
Capture - An open source hardware monitoring agent for Checkmate.

github-license github-repo-size github-commit-activity github-last-commit-data github-languages github-issues-and-prs github-issues go-reference github-actions-go Ask DeepWiki

Capture

An open source hardware monitoring agent

Capture is a hardware monitoring agent that collects hardware information from the host machine and exposes it through a RESTful API. The agent is designed to be lightweight and easy to use.

Features

  • CPU Monitoring
    • Temperature
    • Load
    • Frequency
    • Usage
  • Memory Monitoring
  • Disk Monitoring
    • Usage
    • Inode Usage
    • Read/Write Bytes
  • S.M.A.R.T. Monitoring (Self-Monitoring, Analysis and Reporting Technology) for NVMe, SATA and SAS drives, one entry per drive. Requires smartmontools 7.0 or newer and, on most systems, running Capture as root. Not available in the Docker image, which does not include smartctl
    • Model, serial number, firmware and capacity
    • Overall health, temperature, power-on hours
    • Reallocated, pending and uncorrectable sectors (SATA/SAS); wear, spare and media errors (NVMe)
    • Warnings from smartctl, e.g. failing attributes or errors in the drive's error log
  • Network Monitoring
  • Docker Container Monitoring
  • GPU Monitoring (coming soon)

Quick Start (Docker)

docker run -d \
    -v /etc/os-release:/etc/os-release:ro \
    -p 59232:59232 \
    -e API_SECRET=your-secret-key \
    ghcr.io/bluewave-labs/capture:latest

Quick Start (Docker Compose)

services:
  # Capture service
  capture:
    image: ghcr.io/bluewave-labs/capture:latest
    container_name: capture
    restart: unless-stopped
    ports:
      - "59232:59232"
    environment:
      - API_SECRET=REPLACE_WITH_YOUR_SECRET # Required authentication key. Do not forget to replace this with your actual secret key.
      - GIN_MODE=release
      - LISTEN=0.0.0.0
    volumes:
      - /etc/os-release:/etc/os-release:ro

Configuration

Variable Description Default Required
API_SECRET Authentication key (Must match the secret you enter on Checkmate) - Yes
PORT Server port number 59232 No
LISTEN IP address to bind to (e.g. 127.0.0.1 or ::1), without a port or IPv6 brackets. Use an interface's IP address, not its name. 0.0.0.0 No
GIN_MODE Gin(web framework) mode. Debug is for development release No
SMART_DEVICES Comma-separated SMART devices as path or path:type, e.g. /dev/sdb:sat,/dev/sdc:sat. Overrides the device type from smartctl --scan for those paths (symlinks such as /dev/disk/by-id/... are matched to the scanned disk) and adds devices the scan misses. Checked at startup; an invalid value stops Capture with an error - No

Example configurations:

# Minimal
API_SECRET=your-secret-key ./capture

# Complete
API_SECRET=your-secret-key LISTEN=0.0.0.0 PORT=59232 GIN_MODE=release ./capture

# Local connections only (for a host installation with a local reverse proxy)
API_SECRET=your-secret-key LISTEN=127.0.0.1 ./capture

When LISTEN is unset or empty, Capture listens on all IPv4 interfaces (0.0.0.0). For containers, keep LISTEN=0.0.0.0 to allow connections through Docker port mappings or from other containers.

Installation Options

Docker (Recommended)

Pull and run the official image:

docker run -d \
    -v /etc/os-release:/etc/os-release:ro \
    -p 59232:59232 \
    -e API_SECRET=your-secret-key \
    ghcr.io/bluewave-labs/capture:latest

Or build locally:

docker buildx build -t capture .
docker run -d -v /etc/os-release:/etc/os-release:ro -p 59232:59232 -e API_SECRET=your-secret-key capture

Docker options explained:

  • -v /etc/os-release:/etc/os-release:ro: Platform detection
  • -p 59232:59232: Port mapping
  • -e API_SECRET: Required authentication key
  • -d: Detached mode

Helm

You can deploy Capture on a Kubernetes cluster using the provided Helm chart.

  1. Go to the Helm chart directory:

    cd deployment/helm/capture
    
  2. Customize values.yaml and set your API_SECRET.

  3. Install the chart:

    helm install capture .
    

For detailed instructions, refer to the Helm Installation Guide.

System Installation

Choose one of these methods:

  1. Pre-built Binaries: Download from GitHub Releases

  2. Go Package:

    go install github.com/bluewave-labs/capture/cmd/capture@latest
    
  3. Build from Source:

    git clone git@github.com:bluewave-labs/capture
    cd capture
    just build   # or: go build -o dist/capture ./cmd/capture/
    

Linux Systemd Service

An install script is provided at deployment/linux/install.sh. It automatically detects your CPU architecture, downloads the latest release from GitHub, installs the binary to /usr/local/bin, and registers a systemd service.

Requirements: curl, tar, and a system running systemd. Must be run as root.

  1. Download and run in one step:

    curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh | sudo bash
    

    The script will prompt you for API_SECRET if it is not supplied as an argument.

  2. Supply options inline if preferred:

    curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh \
        | sudo bash -s -- --api-secret "your-secret-key"
    
  3. All available options:

    curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh \
        | sudo bash -s -- \
            --api-secret "your-secret-key" \
            --port 59232 \
            --listen 0.0.0.0 \
            --install-dir /usr/local/bin \
            --service-name capture
    

    Or download the script first and run it locally:

    curl -fsSL -o install.sh https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh
    sudo bash install.sh --api-secret "your-secret-key"
    
  4. Full option reference:

    Option Description Default
    --api-secret Authentication key (required) (prompted)
    --port Port the agent listens on 59232
    --listen IP address the agent binds to 0.0.0.0
    --install-dir Directory to install the binary /usr/local/bin
    --service-name systemd service name capture
  5. After installation, manage the service with systemctl:

    systemctl status capture
    systemctl stop capture
    systemctl start capture
    systemctl restart capture
    journalctl -u capture -f
    

Manual setup

If you prefer to configure the service manually, a template service file is provided at deployment/linux/capture.service.

  1. Edit the service file with your binary path, user, group, and secret key:

    nano deployment/linux/capture.service
    
  2. Copy it to the systemd unit directory:

    cp deployment/linux/capture.service /etc/systemd/system/
    
  3. Reload, enable, and start the service:

    systemctl daemon-reload
    systemctl enable capture
    systemctl start capture
    
  4. Verify the service is running:

    systemctl status capture
    

macOS Launchd Service

An install script is provided at deployment/macos/install.sh. It automatically detects your CPU architecture, downloads the latest release from GitHub, installs the binary to /usr/local/bin, and registers a system-wide launchd daemon.

Requirements: curl, tar, macOS, and root access via sudo.

  1. Download and run in one step:

    curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh | sudo bash
    

    The script will prompt you for API_SECRET if it is not supplied as an argument.

  2. Supply options inline if preferred:

    curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh \
        | sudo bash -s -- --api-secret "your-secret-key"
    
  3. All available options:

    curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh \
        | sudo bash -s -- \
            --api-secret "your-secret-key" \
            --port 59232 \
            --listen 0.0.0.0 \
            --install-dir /usr/local/bin \
            --service-name com.bluewavelabs.capture
    

    Or download the script first and run it locally:

    curl -fsSL -o install.sh https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh
    sudo bash install.sh --api-secret "your-secret-key"
    
  4. Full option reference:

    Option Description Default
    --api-secret Authentication key (required) (prompted)
    --port Port the agent listens on 59232
    --listen IP address the agent binds to 0.0.0.0
    --install-dir Directory to install the binary /usr/local/bin
    --service-name launchd label and plist filename com.bluewavelabs.capture
  5. After installation, manage the service with launchctl:

    sudo launchctl load /Library/LaunchDaemons/com.bluewavelabs.capture.plist
    sudo launchctl start com.bluewavelabs.capture
    sudo launchctl list | grep com.bluewavelabs.capture
    tail -f /var/log/com.bluewavelabs.capture.log
    

Manual setup

If you prefer to configure the service manually, a template plist is provided at deployment/macos/capture.plist.

  1. Edit the plist with your binary path, working directory, secret key, and any other settings you need:

    nano deployment/macos/capture.plist
    
  2. Copy it to the launchd daemon directory and set the required permissions:

    cp deployment/macos/capture.plist /Library/LaunchDaemons/com.bluewavelabs.capture.plist
    chown root:wheel /Library/LaunchDaemons/com.bluewavelabs.capture.plist
    chmod 644 /Library/LaunchDaemons/com.bluewavelabs.capture.plist
    
  3. Load and start the service:

    sudo launchctl load /Library/LaunchDaemons/com.bluewavelabs.capture.plist
    sudo launchctl start com.bluewavelabs.capture
    
  4. Verify the service is running:

    sudo launchctl list | grep com.bluewavelabs.capture
    

Windows Service

A PowerShell install script is provided at deployment/windows/install.ps1. It automatically detects your CPU architecture, downloads the latest release from GitHub, installs the binary, and registers a Windows service.

Requirements: PowerShell 5.1+ and an Administrator terminal.

  1. Open PowerShell as Administrator and run in one step:

    Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
    Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1 | Invoke-Expression
    

    The script will prompt you for API_SECRET if it is not supplied as a parameter.

  2. Supply parameters inline if preferred:

    & ([scriptblock]::Create(
        (Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1)
    )) -APISecret "your-secret-key"
    
  3. All available parameters:

    & ([scriptblock]::Create(
        (Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1)
    )) -APISecret "your-secret-key" -Port 59232 -Listen "0.0.0.0" -InstallDir "C:\Program Files\Capture" -ServiceName "capture"
    

    Or download the script first and run it locally:

    Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1 -OutFile install.ps1
    Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
    .\install.ps1 -APISecret "your-secret-key"
    
  4. Full parameter reference:

    Parameter Description Default
    -APISecret Authentication key (required) (prompted)
    -Port Port the agent listens on 59232
    -Listen IP address the agent binds to 0.0.0.0
    -InstallDir Directory to install the binary C:\Program Files\Capture
    -ServiceName Windows service name capture
  5. After installation, manage the service with standard PowerShell cmdlets:

    Get-Service capture
    Stop-Service capture
    Start-Service capture
    Restart-Service capture
    

Reverse Proxy and SSL

You can use a reverse proxy in front of the Capture service to handle HTTPS requests and SSL termination.

Caddy

├deployment/reverse-proxy-compose/
├── caddy/
│   └── Caddyfile
└── caddy.compose.yml
  1. Go to the deployment/reverse-proxy-compose directory

    cd deployment/reverse-proxy-compose
    
  2. Replace replacewithyourdomain.com with your actual domain in deployment/reverse-proxy-compose/caddy/Caddyfile

  3. Set API_SECRET environment variable for the Capture service in deployment/reverse-proxy-compose/caddy.compose.yml.

  4. Ensure your domain’s DNS A/AAAA records point to this server’s IP.

  5. Open inbound TCP ports 80 and 443 on your firewall/security group.

Start the Caddy reverse proxy

docker compose -f caddy.compose.yml up -d

Endpoints

  • Base URL: http://<host>:<PORT> (default port 59232)
  • Authentication: Every /api/v1/** route requires Authorization: Bearer $API_SECRET. /health stays public so you can use it for liveness checks.
Method Path Auth Description Notes
GET /health ❌ Liveness probe that returns "OK". Useful for container orchestrators.
GET /api/v1/metrics ✅ Returns the complete capture payload with CPU, memory, disk, host, SMART, network, and Docker data. Aggregates every collector.
GET /api/v1/metrics/cpu ✅ CPU temps, load, and utilization.
GET /api/v1/metrics/memory ✅ Memory totals and usage metrics.
GET /api/v1/metrics/disk ✅ Disk capacity, inode usage, and IO stats.
GET /api/v1/metrics/host ✅ Host metadata (OS, uptime, kernel, etc.).
GET /api/v1/metrics/smart ✅ S.M.A.R.T. health, one entry per drive. Identify drives by serial_number; device paths can change after a reboot.
GET /api/v1/metrics/net ✅ Interface-level network throughput.
GET /api/v1/metrics/docker ✅ Docker container metrics. Use ?all=true to include stopped containers.

All responses share the same envelope:

{
  "data": {
    // collector-specific payload
  },
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": [
    // optional array of error messages if any collectors failed, can be null
  ],
}

Collectors can partially fail; when that happens the API responds with HTTP 207 Multi-Status and fills errors with detailed reasons so you can alert without dropping other metric data.

API Documentation

Our API is documented in accordance with the OpenAPI spec.

You can find the OpenAPI specifications in openapi.yml

Contributing

We welcome contributions! If you would like to contribute, please read the CONTRIBUTING.md file for more information.

Contributors Graph

Star History

Star History Chart

License

Capture is licensed under AGPLv3. You can find the license in the LICENSE file.

Categories

Related apps

Links

Details

Repository
ghcr.io/bluewave-labs/capture:latest
Last Updated2026-11-21
First Seen2025-05-30

Runtime arguments

Network
bridge
Shell
bash
Privileged
false

Template configuration

Listen PortPorttcp

The port where the API endpoint will live.

Target
59232
Value
59232
API SecretVariable

The authorization secret used to validate the connection to Checkmate.

Target
API_SECRET
Default
REPLACE_WITH_YOUR_SECRET
Value
REPLACE_WITH_YOUR_SECRET