Kami Smarthome Suite

Kami SmartHome skill bundle. One-click installer for the entire Kami SmartHome ecosystem with centralized configuration (API key, cameras, notifications) — no more configuring each skill individually.

Overview

Kami SmartHome Suite is the one-stop installer for the kami-smarthome ecosystem. By installing this single skill, users get:

1. Batch download — install all 6 ecosystem skills from ClawHub in one go
2. Guided configuration — interactive setup for API key and notification channels; all skills are ready to use immediately after configuration
3. Centralized config management — to change anything later, edit one file and run configure.sh --distribute to sync

Design principle: Single Source of Truth — one config file controls all skills. Core promise: configure once, run everywhere — once API key and notification channels are set, all 6 skills work out of the box.

Included Skills

This suite bundles the following 6 standalone skills:

#	Skill	Emoji	Description	Use case
1	kami-package-detection	📦	Real-time package/parcel detection on RTSP streams using YOLO-World ONNX	Doorstep delivery alerts
2	kami-image-search	🔍	Periodic frame capture + VLM captioning + FAISS index for natural-language image search	Search historical frames
3	kami-video-search	📹	Continuous video segmentation + VLM scene description + natural-language clip search	Search historical clips
4	kami-fall-detection	🚨	Frame-difference detection + KamiClaw cloud inference for fall events	Elder / lone-resident care
5	kami-conflict-detection	🥊	Multi-person physical conflict (fight/shove) detection with event-driven alarm JSON	Security alerting
6	kami-suspicious-person	🕵️	Stranger recognition via SCRFD + ArcFace, detects unregistered face loitering	Doorway / stranger-loiter alerts

Skill Map

kami-smarthome-suite (this skill — installer entry point)
├── kami-package-detection    ── Package / delivery detection
├── kami-image-search         ── Image search
├── kami-video-search         ── Video recording & search
├── kami-fall-detection       ── Fall detection (cloud API)
├── kami-conflict-detection   ── Conflict / fight detection
└── kami-suspicious-person    ── Stranger / suspicious-person detection

Installation

All Kami SmartHome skills are published on ClawHub and installed via clawhub install.

Option 1: One-click install (recommended)

# Install the suite
clawhub install kami-smarthome-suite

# Run setup.sh — auto-installs all 6 skills + guides centralized config
bash {baseDir}/setup.sh

setup.sh performs:

1. One-shot install of all 6 Kami ecosystem skills from ClawHub
2. Detect / install Python 3.10:
   • Debian/Ubuntu: prefer conda → pyenv → system python3.10 (avoids python3.10-venv sudo dependency)
   • Other systems: prefer system python3.10 → pyenv → conda
   • If none found: auto-install (conda preferred → pyenv as fallback), no sudo required; only pyenv source build will ask for sudo when build-deps are missing
3. Interactive prompts for centralized config (API key, camera URL, notifications)
4. Auto-distribute the centralized config to each skill's local config files

Idempotent — re-running will not reinstall skills that are already present.

Option 2: Install individually

You can also install specific skills directly from ClawHub:

clawhub install kami-package-detection
clawhub install kami-image-search
clawhub install kami-video-search
clawhub install kami-fall-detection
clawhub install kami-conflict-detection
clawhub install kami-suspicious-person

After individual installs, run bash {baseDir}/configure.sh to apply unified configuration.

Guided Setup (read this on first use)

Agent behavior: when this skill is triggered, follow this order:

1. Check whether sub-skills are installed (any missing sub-skill directory means "not installed") → if missing, run bash {baseDir}/setup.sh
2. Check whether kamiclaw_api_key is empty in {baseDir}/kami_config.json → if so, prompt the user
3. If both checks pass, skip the wizard and execute the user's request directly

Step 0: Install sub-skills

• Check: look for sibling directories kami-image-search, kami-video-search, etc. next to {baseDir}
• If missing: run the one-click install:

  bash {baseDir}/setup.sh
  

  This script will: download all 6 sub-skills from ClawHub + create venvs + install dependencies
• If present: skip and proceed to config check

Step 1: Configure KamiClaw API key

• Check: read the kamiclaw_api_key field from {baseDir}/kami_config.json
• If empty: tell the user 4 of the 6 skills require an API key, and prompt for one
• How to obtain: register at https://kamiclaw-skill.kamihome.com (free 200 credits)
• API-dependent skills: image-search, video-search, fall-detection, conflict-detection
• 2 fully-local skills (package-detection, suspicious-person) do not need an API key

Step 2: Configure notification channels

• Check: read the notifications section of {baseDir}/kami_config.json
• If all empty: ask the user whether to set up alarm push (any combination is allowed)
• Supported channels (alarm skills fall-detection / conflict-detection / suspicious-person push automatically when events fire):
  • Feishu Webhook: feishu_webhook_url (+ optional feishu_webhook_secret for signed webhooks) — supported by all 3 alarm skills
  • Telegram Bot: telegram_bot_token + telegram_chat_id — supported by all 3 alarm skills
  • Discord Webhook: discord_webhook_url (push-only) — supported by all 3 alarm skills
  • Discord Bot: discord_bot_token + discord_channel_id (two-way) — fall-detection only
• All channels are optional; skipped channels just fall back to JSON output without push
• ⚠️ Discord / Telegram may be unreachable from some regions. If a proxy is needed, set HTTPS_PROXY in your shell rc (e.g. ~/.bashrc) yourself — the suite intentionally does NOT manage proxy settings

Configuration complete → all skills ready

After the user provides values:

1. Write the values back into the corresponding fields of {baseDir}/kami_config.json
2. Run distribution:

   bash {baseDir}/configure.sh --distribute
   

3. After distribution: tell the user that all skills are ready to use

Updating configuration later

To change the API key or notification channels later:

# Re-run the interactive wizard
bash {baseDir}/configure.sh

# Or edit directly and redistribute
vim {baseDir}/kami_config.json
bash {baseDir}/configure.sh --distribute

Prerequisites

• clawhub CLI installed (used to pull skills from ClawHub)
• Network access (for skill download + KamiClaw API calls from some skills)

Python 3.10 is required. setup.sh selects detection priority by OS family (Debian/Ubuntu prefers conda/pyenv; other systems prefer system python3.10) and auto-installs via conda when missing. Other dependencies are managed by each sub-skill.

Hardware Requirements

Recommended minimum hardware for each skill:

Skill	CPU	Memory (RAM)	Storage	GPU	Notes
kami-package-detection	2+ cores	2 GB	500 MB	not required	YOLO-World ONNX, CPU-only
kami-image-search	2+ cores	2 GB	5 GB+	not required	FAISS index + SQLite frame history
kami-video-search	2+ cores	2 GB	10 GB+	not required	Stores video segments, scales with retention
kami-fall-detection	1+ core	1 GB	200 MB	not required	Local does frame-diff only; inference runs in cloud
kami-conflict-detection	4+ cores	4 GB	1 GB	optional (accelerates)	Local YOLO person detection + multi-frame analysis
kami-suspicious-person	4+ cores	4 GB	1.5 GB	optional (accelerates)	SCRFD + ArcFace ONNX (~1 GB)

Recommended config to run all 6 skills concurrently:

• CPU: 4+ cores (x86_64 / ARM64)
• Memory: 8 GB+
• Storage: 20 GB+ free space
• Network: stable connection (RTSP pull + API calls)
• OS: Linux (Ubuntu 20.04+ recommended)

If you only enable a subset of skills, refer to the corresponding rows above.

Centralized Configuration

Design

The suite uses a central config + auto-distribute model:

kami_config.json (Single Source of Truth)
       │
       ▼  configure.py --distribute
       ├── kami-image-search/image_config.json
       ├── kami-video-search/stream_config.json
       ├── kami-fall-detection/config.json
       ├── kami-package-detection/config.json
       ├── kami-conflict-detection/config.json
       ├── kami-suspicious-person/config.json
       └── ~/.kami/credentials.json (credential cache)

Central config file kami_config.json

Located in the suite directory, it contains the following sections:

Section	Description	Skills affected
kamiclaw_api_key	KamiClaw API key	The 4 cloud-API skills
cameras.default	Camera RTSP URL / device ID	All 6 skills (auto-distributed to each skill's local config)
notifications	Feishu / Telegram / Discord push settings	fall-detection, conflict-detection, suspicious-person
skills.<name>	Per-skill tuning parameters	The corresponding skill

Edit this file once and every skill is configured.

Usage

# Mode 1: interactive wizard (prompts each field)
bash {baseDir}/configure.sh

# Mode 2: set API key directly
bash {baseDir}/configure.sh sk_live_xxxxxxxx

# Mode 3: edit manually then distribute
vim {baseDir}/kami_config.json
bash {baseDir}/configure.sh --distribute

# Mode 4: show current config
bash {baseDir}/configure.sh --show

Distribution Map

All skills use a local config.json-style file (auto-patched on configure.sh --distribute)

Skill	Target file	Distributed fields
kami-fall-detection	config.json	api_key, rtsp_url, feishu_webhook_url, telegram_bot_token, telegram_chat_id, discord_webhook_url, discord_bot_token, discord_channel_id
kami-video-search	stream_config.json	KAMI_API_KEY, STREAM_URL, DEVICE_ID
kami-image-search	image_config.json	KAMIVISION_API_KEY, STREAM_URL, DEVICE_ID
kami-package-detection	config.json	rtsp_url, conf_threshold, run_time (pure local inference, no API key, class_names is NOT distributed)
kami-conflict-detection	config.json	kami_api_key, rtsp_url, feishu_webhook, discord_webhook, telegram_bot_token, telegram_chat_id
kami-suspicious-person	config.json	rtsp_url, feishu_webhook, discord_webhook, telegram_bot_token, telegram_chat_id (pure local inference, no API key)

Each skill's argparse still keeps os.environ.get(...) fallbacks for KAMI_API_KEY, FEISHU_WEBHOOK_URL, TELEGRAM_*, DISCORD_WEBHOOK_URL, HTTPS_PROXY. So power users can still export env vars manually — but the suite no longer manages ~/.kami/kami.env itself.

⚠️ HTTPS_PROXY is not part of kami_config.json. If you need a proxy to reach Discord / Telegram, set it in your shell rc yourself.

Integration with setup.sh

After installing all skills, setup.sh automatically enters the centralized config flow:

• Prompts for API key, camera URL, notification webhooks
• Saves to kami_config.json and distributes to each skill
• If skipped, run bash configure.sh later anytime
• Credentials are cached to ~/.kami/credentials.json and reused on subsequent installs

Per-skill Quick Reference

Skill	Local config file	Source	API key	Camera URL	Webhook
kami-package-detection	config.json	← auto-distributed from kami_config.json	not needed	✅ auto-distributed	not needed
kami-image-search	image_config.json	← auto-distributed from kami_config.json	✅ auto-distributed	✅ auto-distributed	not needed
kami-video-search	stream_config.json	← auto-distributed from kami_config.json	✅ auto-distributed	✅ auto-distributed	not needed
kami-fall-detection	config.json	← auto-distributed from kami_config.json	✅ auto-distributed	✅ auto-distributed	✅ auto-distributed
kami-conflict-detection	config.json	← auto-distributed from kami_config.json	✅ auto-distributed	✅ auto-distributed	✅ auto-distributed
kami-suspicious-person	config.json + face_db/	← auto-distributed from kami_config.json	not needed	✅ auto-distributed	✅ auto-distributed

Privacy Notice

This suite involves camera streams, image capture and face recognition. Please review the following privacy notes before use:

Data handling

Skill	Processing	Data sent to cloud	Data stored locally
kami-package-detection	Pure local inference	none	no persistent storage
kami-image-search	Capture → cloud VLM captioning	image frames (for description and embedding generation)	captured frames, captions, FAISS index
kami-video-search	Recording → cloud VLM captioning	key frames of clips (for description and embedding generation)	video segments, captions
kami-fall-detection	Local frame-diff → cloud AI judgment	changed frames (only when motion is detected)	alarm clips (configurable)
kami-conflict-detection	Local person detection → cloud conflict analysis	multi-frame snapshots (only when multiple people are present)	no persistent storage
kami-suspicious-person	Pure local inference	none	face feature DB (user-built)

Cloud API calls

• 4 skills depend on KamiClaw API (image-search, video-search, fall-detection, conflict-detection)
• Data sent to the cloud is used only for real-time inference and is not persisted nor used for model training
• API traffic uses HTTPS encryption

Local data storage

• Captured frames, video segments, etc. are stored under each skill's working directory and can be cleaned manually
• image-search and video-search honor a retention_days parameter for automatic expiry
• The API key is cached in ~/.kami/credentials.json (mode 600, current user only)

Face data (kami-suspicious-person)

• The face feature database is built and matched fully locally — nothing is uploaded to any server
• Files are stored under face_db/, fully under user control
• Removing the face_db/ directory wipes all face data

User control

• Users freely choose which skills to enable; disabled skills collect nothing
• All camera URLs are user-supplied; skills do not auto-discover or auto-connect cameras
• Users can stop a skill, delete local data, or revoke the API key at any time

Privacy policy details: https://kamiclaw-skill.kamihome.com/privacy

Exit Codes

Exit code	Meaning
0	All skills installed successfully
1	Some skills failed to install (check logs)
2	Prerequisite missing (no clawhub, or neither conda nor pyenv is usable and Python 3.10 cannot be installed)

Troubleshooting

clawhub CLI not available

clawhub: command not found

→ Install the ClawHub CLI first.

A skill failed to install

[!] kami-xxx (failed, exit 1)

→ Retry: clawhub install kami-xxx

KamiClaw API key not configured → Run bash configure.sh or register at https://kamiclaw-skill.kamihome.com

Config changes have no effect → After editing kami_config.json, run bash configure.sh --distribute to push the changes to each skill.