ruvnet--RuView/v2/crates/homecore-server/README.md

homecore-server

homecore-server is the alpha integration binary for HOMECORE. It runs one shared state machine, event bus, service registry, REST/WebSocket API, optional SQLite recorder, automation engine, intent endpoint, BFF gateway, and static dashboard.

It is not a drop-in replacement for the complete Home Assistant API. The exact implemented and deferred surfaces are listed in docs/homecore-capabilities.md.

Security defaults

Authentication fails closed. Set one or more comma-separated bearer tokens:

set HOMECORE_TOKENS=replace-with-a-long-random-token
cargo run -p homecore-server

--insecure-dev-auth explicitly allows any non-empty bearer token and must only be used in an isolated development environment. The browser UI does not contain a default token. Configure allowed browser origins with HOMECORE_CORS_ORIGINS.

Runtime behavior

• SQLite recording is enabled by default at sqlite://homecore.db.
• Entity/device registries are restored from .homecore/storage before recorder states, listeners, automations, and API startup.
• The latest recorder state for each entity is restored deterministically. Restored snapshots retain their timestamps and carry a homecore.restore context marker; malformed rows are logged and isolated.
• Synthetic entities are disabled by default; opt in with --seed-demo-entities.
• Automations can be loaded with --automations <file> or HOMECORE_AUTOMATIONS.
• Ctrl-C initiates graceful HTTP shutdown and emits HomeCoreStop.
• The ruvector feature enables the recorder's semantic index.
• Plugin and HAP crates are libraries in this workspace, but this binary does not claim to load plugins or advertise a HomeKit server yet.

API

All API requests require Authorization: Bearer <token>.

curl -H "Authorization: Bearer $HOMECORE_TOKEN" \
  http://127.0.0.1:8123/api/states

curl -X POST \
  -H "Authorization: Bearer $HOMECORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"light.kitchen"}' \
  http://127.0.0.1:8123/api/services/light/turn_on

curl -X POST \
  -H "Authorization: Bearer $HOMECORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"utterance":"turn on light.kitchen","language":"en"}' \
  http://127.0.0.1:8123/api/intent/handle

Built-in executable services are homecore.ping, homecore.snapshot_state, and turn_on/turn_off/toggle for the homeassistant, light, and switch domains. Unsupported services are left unregistered and return an error rather than a false acknowledgement.

Configuration

Flag	Environment	Default
--bind	HOMECORE_BIND	0.0.0.0:8123
--db	HOMECORE_DB	sqlite://homecore.db
--storage-dir	HOMECORE_STORAGE_DIR	.homecore/storage
--restore-limit	HOMECORE_RESTORE_LIMIT	100000
--location-name	HOMECORE_LOCATION	Home
--automations	HOMECORE_AUTOMATIONS	unset
--insecure-dev-auth	HOMECORE_INSECURE_DEV_AUTH	false
--seed-demo-entities	—	false
--no-recorder	—	false

Validation

cargo test -p homecore-server
cargo clippy -p homecore-server --all-targets --all-features -- -D warnings