Homecore Integration Setup
Relevant source files
The following files were used as context for generating this wiki page:
Homecore serves as the native Rust stack for RuView, providing a concurrent state engine, event bus, and an authenticated API compatible with Home Assistant. The integration setup involves configuring the homecore-server, which wires together core registries, a recorder for state history, and optional features like WebAssembly (WASM) plugins and the HomeKit Accessory Protocol (HAP).
Developers interact with the Homecore stack through a dedicated metaharness. This harness maps implementation capabilities to validation commands, exposes a Model Context Protocol (MCP) server for agent tools, and facilitates repository exploration via Claude Code or Codex adapters.
Sources: v2/crates/homecore-api/README.md, harness/homecore/README.md, harness/homecore/src/capabilities.js:154-162
Core Architecture and Components
Homecore integration relies on a modular architecture where the homecore-server acts as the primary orchestrator. It integrates multiple specialized crates to handle state, automation, and external communications.
System Components
| Component | Function | Implementation Status |
|---|---|---|
| Core Runtime | Manages entity/device registries and event buses. | Implemented |
| Recorder | Persists state history to SQLite and handles startup restore. | Implemented |
| Automation | Evaluates triggers (state, time, event) and executes services. | Implemented |
| API Server | Provides Axum-based REST and WebSocket endpoints. | Implemented |
| WASM Plugins | Loads bounded, signature-verified external logic via Wasmtime. | Feature-Gated |
| HAP Server | Wires TCP handling and pairing for HomeKit compatibility. | Feature-Gated |
Sources: harness/homecore/src/capabilities.js:25-152, v2/crates/homecore-api/README.md
Data Flow Diagram
The following diagram illustrates how the homecore-server orchestrates internal modules and external interfaces.
The diagram shows the server wiring the core logic, API, and protocol adapters into a single process.
Sources: harness/homecore/src/capabilities.js:141-147, v2/crates/homecore-api/README.md
Developer Metaharness Setup
The Homecore metaharness (harness/homecore) is the developer-facing interface for the Rust stack. It is a WASM-first tool that provides source-cited guidance and diagnostics without starting a full home server.
Installation and Initialization
The metaharness is packaged for NPM. You execute it using npx or by running the source entry point during development.
# Execute published package
npx homecore guidance
# Execute from source (development)
node harness/homecore/bin/cli.js doctor --repo .
Sources: harness/homecore/README.md:1-12, harness/homecore/package.json:9-12
Verification Profiles
Integration setup requires validating specific layers of the stack. The metaharness provides profiles for targeted testing:
- core: Validates state, registries, and the event bus.
- wasm: Exercises Wasmtime-specific Rust tests and verify signatures.
- hap: Validates the HomeKit Accessory Protocol implementation.
Sources: harness/homecore/README.md:19-21, harness/homecore/src/capabilities.js:82-88
API and Registry Configuration
Homecore exposes a wire-compatible Axum REST and WebSocket server. The setup requires defining entity states and configuring authentication via long-lived access tokens.
REST Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/states | Lists all entity states and attributes. |
GET | /api/states/:id | Fetches a specific entity's state. |
POST | /api/states/:id | Updates an entity's state and attributes. |
GET | /api/services | Lists all registered services. |
POST | /api/services/:d/:s | Calls a service within a specific domain. |
Sources: v2/crates/homecore-api/README.md:46-54
Startup Restore Logic
Homecore restores system state upon startup to ensure continuity. The process follows a strict order to maintain data integrity:
- Registry Restore: The server restores entity and device registries.
- Recorder State: The system loads the most recent states from the SQLite database.
- Isolation: The server isolates malformed rows within configured limits rather than failing the entire boot process.
Sources: harness/homecore/src/capabilities.js:28-36, harness/homecore/src/guidance.js:87-93
Plugin and Extension Setup
Homecore supports two types of extensions: native compiled-in plugins and external WebAssembly packages.
Plugin Architecture Diagram
The sequence illustrates the feature-gated loading of native vs. WASM plugins.
Sources: harness/homecore/src/capabilities.js:77-88, harness/homecore/src/guidance.js:100-109
WASM Security Requirements
- Feature Gate: Execution through Wasmtime is gated and must be explicitly enabled.
- Signature Checking: External plugins must be path-checked and signature-verified.
- Boundary Enforcement: The harness never loads arbitrary native dynamic libraries.
Sources: harness/homecore/README.md:57-61, harness/homecore/src/capabilities.js:89-93
Integration Constraints and Limitations
Successful integration requires adhering to the following repository-enforced policies:
- Read-Only Default: Both the MCP server and host adapters (Claude/Codex) are read-only by default.
- Double Opt-in: Any operation that writes to the workspace requires both the
--allow-writeand--confirmflags. - Dependency Bounding: The metaharness kernel validates the MCP server specification and reports the actual backend (WASM vs. native fallback).
- No Self-Promotion: Generated learning candidates or shared knowledge records require manual review and cannot self-promote to the canonical corpus.
Sources: harness/homecore/README.md:28-38, harness/homecore/AGENTS.md:7-14, CLAUDE.md:65-72
Homecore integration setup provides a robust, security-first environment for RF-aware smart home applications. By leveraging the Rust stack's concurrent core and the metaharness's validation tools, developers can ensure that integrations are deterministic and source-cited.