Linky

A simple Homebridge plugin to remotely list and control your HomeKit devices over the internet via a secure API key.

Features

• 📋 List all HomeKit devices with metadata
• 🔄 Get real-time device states
• 🎛️ Control devices (On/Off/Set characteristics)
• 🔐 API Key authentication (secure and rotatable)
• 📊 Built-in /metrics Prometheus endpoint
• 📡 Auto-detects device reachability and status
• ⚡ Fully configurable inside Homebridge UI
• 🚀 Fully automated GitHub Actions release pipeline (with ChatGPT Release Notes!)

Installation

npm install -g homebridge-linky

Configuration (inside Homebridge UI)

| Field | Description | |:------|:------------| | port | Port the Linky server listens on (default: 8081) | | apiKey | (Optional) Predefined API key. If blank, a secure random key is generated. |

API Reference

All API requests require the header:

x-linky-key: YOUR_API_KEY

| Endpoint | Method | Description | |:---------|:-------|:------------| | / | GET | Welcome route with Linky status | | /healthz | GET | Health check route | | /metrics | GET | Prometheus-formatted metrics | | /config | GET | Current server config | | /rotate-key-secret | GET | Get the secret for rotating the API key | | /rotate-key | POST | Rotate the API key (requires x-linky-admin header) | | /devices | GET | List all HomeKit devices | | /device/:id | GET | Get state of specific device | | /device/:id/on | POST | Turn a device ON | | /device/:id/off | POST | Turn a device OFF | | /device/:id/set | POST | Set a specific characteristic |

🧠 Auto-Generated API Key Support

If apiKey is omitted from the config, Linky will:

• Automatically generate a secure API key
• Persist it to Homebridge config using the Homebridge UI API (default port: 8581)
• Log a warning in the console with a message about key generation

To override this behavior:

• Provide your own apiKey in the config
• Or change the uiPort in config if your UI runs on a different port

Authentication

• All normal API requests require a valid x-linky-key header.
• API keys can be rotated at runtime securely via the /rotate-key endpoint.

Metrics

Exposes a Prometheus-friendly /metrics endpoint:

| Metric | Description | |:-------|:------------| | linky_uptime_seconds | Server uptime | | linky_device_count | Total registered devices | | linky_device_reachable_count | Currently reachable devices | | linky_memory_heap_total_bytes | Node.js heap memory total | | linky_memory_heap_used_bytes | Node.js heap memory used | | linky_cpu_load_average_1m/5m/15m | CPU load averages |

Contributing & Release Process

Linky uses a fully automated release pipeline powered by GitHub Actions:

• Every push to the main branch triggers:
  • npm version minor bump (e.g., v0.2.0 → v0.3.0)
  • Builds and publishes a new version to NPM
  • Generates GitHub Release Notes automatically using ChatGPT (if available)
  • Creates a new GitHub Release with the generated notes
  • Cleans up version bumps after publish, even on failure

Pre-commit hooks (powered by Husky) automatically run:

• Code formatting via Prettier
• Linting via ESLint
• TypeScript compilation
• Build script validation

💬 If your OpenAI API quota is exceeded, Linky falls back to static release notes ("Minor improvements and bug fixes.") to ensure uninterrupted publishing.

Requirements

• GitHub Secrets:
  • NPM_TOKEN — for publishing to NPM.
  • OPENAI_API_KEY — (optional) for generating smarter release notes.

Manual Publishing (Optional)

If needed, you can manually trigger a build and publish:

npm run build
npm version minor
npm publish

✅ Otherwise, everything happens automatically when you push to main!

License

MIT © 2025 oorrwullie

🤝 Contributing

We welcome contributions from the community! Please read our Contributing Guidelines before submitting a pull request.

🛡️ Code of Conduct

We expect all contributors to follow our Code of Conduct to foster a welcoming environment.

🔒 Security

If you discover a vulnerability, please follow our Security Policy for responsible disclosure.

🙌 Contributors

Thanks to these amazing people for helping improve Linky!