capture
Docker app from LubricantJam's Repository
Capture - An open source hardware monitoring agent for Checkmate.
Requirements
Overview
Readme
View on GitHubgithub-license
github-repo-size
github-commit-activity
github-last-commit-data
github-languages
github-issues-and-prs
github-issues
go-reference
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
- Quick Start (Docker)
- Quick Start (Docker Compose)
- Configuration
- Installation Options
- 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, 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.
Go to the Helm chart directory:
cd deployment/helm/captureCustomize
values.yamland set yourAPI_SECRET.Install the chart:
helm install capture .
For detailed instructions, refer to the Helm Installation Guide.
System Installation
Choose one of these methods:
Pre-built Binaries: Download from GitHub Releases
Go Package:
go install github.com/bluewave-labs/capture/cmd/capture@latestBuild 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.
Download and run in one step:
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh | sudo bashThe script will prompt you for
API_SECRETif it is not supplied as an argument.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"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 captureOr 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"Full option reference:
Option Description Default --api-secretAuthentication key (required) (prompted) --portPort the agent listens on 59232--listenIP address the agent binds to 0.0.0.0--install-dirDirectory to install the binary /usr/local/bin--service-namesystemd service name captureAfter 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.
Edit the service file with your binary path, user, group, and secret key:
nano deployment/linux/capture.serviceCopy it to the systemd unit directory:
cp deployment/linux/capture.service /etc/systemd/system/Reload, enable, and start the service:
systemctl daemon-reload systemctl enable capture systemctl start captureVerify 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.
Download and run in one step:
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh | sudo bashThe script will prompt you for
API_SECRETif it is not supplied as an argument.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"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.captureOr 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"Full option reference:
Option Description Default --api-secretAuthentication key (required) (prompted) --portPort the agent listens on 59232--listenIP address the agent binds to 0.0.0.0--install-dirDirectory to install the binary /usr/local/bin--service-namelaunchd label and plist filename com.bluewavelabs.captureAfter 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.
Edit the plist with your binary path, working directory, secret key, and any other settings you need:
nano deployment/macos/capture.plistCopy 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.plistLoad and start the service:
sudo launchctl load /Library/LaunchDaemons/com.bluewavelabs.capture.plist sudo launchctl start com.bluewavelabs.captureVerify 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.
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-ExpressionThe script will prompt you for
API_SECRETif it is not supplied as a parameter.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"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"Full parameter reference:
Parameter Description Default -APISecretAuthentication key (required) (prompted) -PortPort the agent listens on 59232-ListenIP address the agent binds to 0.0.0.0-InstallDirDirectory to install the binary C:\Program Files\Capture-ServiceNameWindows service name captureAfter 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
Go to the
deployment/reverse-proxy-composedirectorycd deployment/reverse-proxy-composeReplace
replacewithyourdomain.comwith your actual domain in deployment/reverse-proxy-compose/caddy/CaddyfileSet
API_SECRETenvironment variable for the Capture service in deployment/reverse-proxy-compose/caddy.compose.yml.Ensure your domain’s DNS A/AAAA records point to this server’s IP.
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 port59232) - Authentication: Every
/api/v1/**route requiresAuthorization: Bearer $API_SECRET./healthstays 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 GraphStar History
License
Capture is licensed under AGPLv3. You can find the license in the LICENSE file.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/bluewave-labs/capture:latestRuntime arguments
- Network
bridge- Shell
bash- Privileged
- false
Template configuration
The port where the API endpoint will live.
- Target
- 59232
- Value
- 59232
The authorization secret used to validate the connection to Checkmate.
- Target
- API_SECRET
- Default
- REPLACE_WITH_YOUR_SECRET
- Value
- REPLACE_WITH_YOUR_SECRET