capture

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
• Quick Start (Docker)
• Quick Start (Docker Compose)
• Configuration
• Installation Options
  • Docker (Recommended)
  • Helm
  • System Installation
  • Linux Systemd Service
  • macOS Launchd Service
  • Windows Service
  • Reverse Proxy and SSL
    • Caddy
• Endpoints
• API Documentation
• Contributing
• Star History
• License

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 and SATA drives. Requires smartmontools 7.0 or newer
• 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
    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
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 PORT=59232 GIN_MODE=release ./capture

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 [email protected]: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 \
           --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
   --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 \
           --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
   --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 -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
   -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. drive health information.
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.

Star History

License

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