Prefab is an application that provides a simple HTTP interface to HomeKit data. As of this writing the native HomeKit APIs are only available on iOS based systems. The goal of this app is to provide HomeKit access to macOS. The Prefab application provides access to data provided by HomeKit while the prefab CLI tool provides a simple client to request HomeKit data and provide shell access.
- Xcode: Version 15.0 or later
- macOS: 14.2 or later (for macOS target)
- iOS: 17.2 or later (for iOS target)
- HomeKit Setup: Physical HomeKit accessories or HomeKit simulator
- Apple Developer Account: Required for HomeKit entitlements and code signing
This project uses Swift Package Manager through Xcode with the following dependencies:
- Hummingbird: Swift HTTP server framework
- swift-http-types: Modern HTTP types for Swift
- swift-argument-parser: Command-line argument parsing
git clone https://github.com/kellyp/prefab.git
cd prefab
open prefab.xcodeproj
Dependencies are automatically resolved by Xcode when you first open the project. If you need to manually resolve them:
- In Xcode, go to File → Packages → Resolve Package Versions
- Wait for Xcode to download and resolve all Swift packages
- Select the prefab project in the navigator
- Select the Prefab target
- Go to Signing & Capabilities
- Select your development team
- Ensure the HomeKit capability is enabled
- Select your target device or simulator
- Press ⌘+B to build, or ⌘+R to build and run
# Build all targets
xcodebuild -project prefab.xcodeproj -scheme Prefab build
# Build for specific destination
xcodebuild -project prefab.xcodeproj -scheme Prefab -destination 'platform=macOS' build
The build creates two main products:
- Prefab.app: The main SwiftUI application with HTTP server
- prefab: The command-line tool (embedded in the app bundle)
- Press ⌘+U to run all tests
- Or use Product → Test from the menu
# Run all tests
xcodebuild test -project prefab.xcodeproj -scheme Prefab -destination 'platform=macOS'
# Run specific test plan
xcodebuild test -project prefab.xcodeproj -testPlan Prefab -destination 'platform=macOS'
- prefabTests: Unit tests for core functionality
- prefabUITests: UI automation tests
From Xcode:
- Select the Prefab scheme
- Press ⌘+R to run
From Command Line:
# Option 1: Build to a specific directory (most predictable)
xcodebuild -project prefab.xcodeproj -scheme Prefab -destination 'platform=macOS' \
-derivedDataPath ./build build
open ./build/Build/Products/Debug-maccatalyst/Prefab.app
# Option 2: Use default derived data path
xcodebuild -project prefab.xcodeproj -scheme Prefab -destination 'platform=macOS' build
open ~/Library/Developer/Xcode/DerivedData/prefab-*/Build/Products/Debug-iphoneos/Prefab.app
# Option 3: Build and run in one command with custom path
xcodebuild -project prefab.xcodeproj -scheme Prefab -destination 'platform=macOS' \
-derivedDataPath ./build build && \
open ./build/Build/Products/Debug-maccatalyst/Prefab.app
The application will:
- Start the HTTP server on
http://localhost:8080
(accessible at0.0.0.0:8080
) - Advertise the service via mDNS/Bonjour as "Prefab HomeKit Server" (
_prefab._tcp.
) - Display a SwiftUI interface showing your HomeKit homes
- Begin serving HomeKit data via REST API
The server automatically advertises itself using mDNS (Bonjour) with:
- Service Type:
_prefab._tcp.
- Service Name: "Prefab HomeKit Server"
- Port: 8080
- TXT Record: Contains version info and API details
You can discover the service using:
# Using dns-sd command-line tool
dns-sd -B _prefab._tcp.
# Or browse all services
dns-sd -B _tcp.
The CLI tool is embedded within the app bundle. To use it:
# Navigate to the app bundle
cd build/Build/Products/Debug/
# Or if running from Xcode's DerivedData
./prefab --help
Available CLI commands:
# Get all homes
./prefab homes
# Get specific home details
./prefab home --id [HOME_ID]
# Get rooms in a home
./prefab rooms --home-id [HOME_ID]
# Get accessories
./prefab accessories --home-id [HOME_ID]
# Update accessory
./prefab update-accessory --id [ACCESSORY_ID] --value [VALUE]
Once the app is running, you can interact with the HTTP API locally or from other devices on your network:
# Local access
curl http://localhost:8080/homes
# Network access (replace with actual IP)
curl http://192.168.1.100:8080/homes
# Get specific home
curl http://localhost:8080/homes/[HOME_ID]
# Get rooms in a home
curl http://localhost:8080/homes/[HOME_ID]/rooms
# Get accessories in a home
curl http://localhost:8080/homes/[HOME_ID]/accessories
mDNS/Bonjour Discovery: Other devices can discover the service automatically and connect using the advertised hostname and port.
- Ensure you have HomeKit accessories set up on your iOS device, or use the HomeKit simulator
- Build and run the app on your Mac
- Grant HomeKit permissions when prompted
- Verify the API is responding at
http://localhost:8080/homes
- Edit Swift files in Xcode
- The HTTP server will restart automatically when you rebuild
- Use the CLI tool or curl to test API changes
- Run tests to ensure nothing is broken
- Console Logs: Check Console.app for detailed logging output
- Network Debugging: Use tools like curl or Postman to test API endpoints
- HomeKit Debugging: Use the Home app on iOS to verify HomeKit state
If you get 403 Forbidden
responses:
- Check that HomeKit permission is granted in System Preferences
- Verify the HomeKit entitlement is properly configured
- Ensure you're signed with a valid developer certificate
If dependencies fail to resolve:
- Clean build folder (⌘+Shift+K)
- Reset package caches: File → Packages → Reset Package Caches
- Manually resolve packages: File → Packages → Resolve Package Versions
If the HTTP server fails to start:
- Check that port 8080 is not in use by another process
- Review console logs for specific error messages
- Ensure proper code signing for network access
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request