Homebridge

Control smart home devices via Homebridge Config UI X REST API. Use to list, turn on/off, adjust brightness, color, or temperature of HomeKit-compatible accessories. Supports lights, switches, thermostats, fans, and other Homebridge-managed devices.

Security Scan

The skill's code, instructions, and required credentials align with its stated purpose of controlling a local Homebridge instance; there are only minor documentation inconsistencies to be aware of.

Purpose & Capability

Name/description match the code and SKILL.md: the script and examples talk to Homebridge Config UI X REST API and require Homebridge admin credentials. There are no unrelated credentials, binaries, or install steps requested.

Instruction Scope

Instructions stay within the Homebridge API domain (authenticate, list, get, set). Minor documentation inconsistencies: the Python module docstring mentions reading ~/.clawdbot/clawdbot.json under skills.entries.homebridge, but both SKILL.md and the implemented load_config() function actually use ~/.clawdbot/credentials/homebridge.json. SKILL.md also shows curl examples that use environment variables (HOMEBRIDGE_URL/HOMEBRIDGE_USERNAME/HOMEBRIDGE_PASSWORD) while the provided script expects the credentials file; this is a usability/documentation mismatch but not a security mismatch.

Install Mechanism

No install spec (instruction-only with an included script). No downloads or external installers; the included Python script uses only standard library modules. This has low install risk.

Credentials

The only secret required is the Homebridge admin username/password stored in a local credentials file; this is proportional to managing Homebridge devices. The skill does not request unrelated service keys or system credentials.

Persistence & Privilege

always:false (no forced persistence). The skill reads a local credentials file but does not modify other skills, system settings, or persist extra state. It does not request elevated system privileges.

Assessment

This skill appears coherent for controlling a Homebridge instance, but check a few things before installing: 1) Verify the credential file path (~/.clawdbot/credentials/homebridge.json) exists and contains correct values; the code and docs are slightly inconsistent about paths—use the credentials file path shown in SKILL.md or the script. 2) Keep the Homebridge instance on a trusted/local network (avoid exposing the admin API to the public Internet). 3) Restrict filesystem permissions on the credentials file (readable only by your user). 4) Inspect the provided script (you already have it) to confirm it meets your expectations—it's pure Python using standard libs. 5) Prefer creating a least-privilege Homebridge account if possible rather than using a full admin account. 6) Confirm you trust the skill publisher/source (homepage is upstream project, but the registry source is unknown). If any of these sound risky for you, do not install or run the script until addressed.

Homebridge Control

Control smart home devices through Homebridge Config UI X's REST API.

Prerequisites

1. Homebridge with Config UI X installed and running
2. Credentials file at ~/.clawdbot/credentials/homebridge.json:

   {
     "url": "https://homebridge.local:8581",
     "username": "admin",
     "password": "your-password"
   }
   

API Overview

Homebridge Config UI X exposes a REST API. View full documentation at {HOMEBRIDGE_URL}/swagger.

Authentication

All API calls require a Bearer token. Obtain it first:

# Get auth token
TOKEN=$(curl -s -X POST "${HOMEBRIDGE_URL}/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"${HOMEBRIDGE_USERNAME}\",\"password\":\"${HOMEBRIDGE_PASSWORD}\"}" \
  | jq -r '.access_token')

Common Operations

List All Accessories

curl -s "${HOMEBRIDGE_URL}/api/accessories" \
  -H "Authorization: Bearer ${TOKEN}" | jq

Response includes accessory uniqueId, serviceName, type, and current values.

Get Accessory Layout (Rooms)

curl -s "${HOMEBRIDGE_URL}/api/accessories/layout" \
  -H "Authorization: Bearer ${TOKEN}" | jq

Control an Accessory

Use PUT to update accessory characteristics:

# Turn on a light/switch
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "On", "value": true}'

# Turn off
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "On", "value": false}'

# Set brightness (0-100)
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "Brightness", "value": 50}'

# Set color (Hue: 0-360, Saturation: 0-100)
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "Hue", "value": 240}'

# Set thermostat target temperature
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "TargetTemperature", "value": 22}'

Common Characteristic Types

Type	Values	Description
On	true/false	Power state
Brightness	0-100	Light brightness %
Hue	0-360	Color hue in degrees
Saturation	0-100	Color saturation %
ColorTemperature	140-500	Color temp in Mired
TargetTemperature	10-38	Thermostat target °C
TargetHeatingCoolingState	0-3	0=Off, 1=Heat, 2=Cool, 3=Auto
RotationSpeed	0-100	Fan speed %
Active	0/1	Active state (fans, etc.)

Using the Scripts

For convenience, use the provided scripts:

List Accessories

scripts/homebridge_api.py list
scripts/homebridge_api.py list --room "Living Room"
scripts/homebridge_api.py list --type Lightbulb

Control Devices

# Turn on/off
scripts/homebridge_api.py set <uniqueId> On true
scripts/homebridge_api.py set <uniqueId> On false

# Adjust brightness
scripts/homebridge_api.py set <uniqueId> Brightness 75

# Set color
scripts/homebridge_api.py set <uniqueId> Hue 120
scripts/homebridge_api.py set <uniqueId> Saturation 100

Get Accessory Status

scripts/homebridge_api.py get <uniqueId>

Tips

• Find your accessory's uniqueId by listing all accessories first
• The API documentation at /swagger shows all available endpoints
• Characteristic names are case-sensitive (use On not on)
• Some accessories may have multiple services; check the response for service types
• Token expires after some time; re-authenticate if you get 401 errors