How eshpelin/nurby works
Nurby is a self-hosted camera NVR and AI surveillance platform. Its main workflow takes camera streams through ingestion and perception, turns detections into identities, events, journeys, and searchable descriptions, then exposes those results through the web/API and agent for review or automation. Rules can trigger notifications and physical actions; separate capabilities include Guardian care workflows, voice/audio, MQTT, and external integrations. Some subsystem links are documented but their implementation was not sampled, so those links are dashed and marked unverified.
Main entry points: pipeline.py Perception pipeline · manager.py Stream ingestion · main.py REST and WebSocket API · llm.py Ask agent
Components 26
Capture and perception
- Stream ingestion
services/ingestion/manager.py - Perception pipeline
services/perception/pipeline.py - Vision descriptions
services/perception/vlm.py - Audio processing
services/perception/audio/router.py - Perception workers
services/perception/main.py
Intelligence and history
- Incidents and journeys
services/perception/incident_tracker.py - Journey tracking
services/perception/journey_tracker.py - Semantic search
services/search/query.py - Text embeddings
services/search/embeddings.py - Ask agent
services/agent/llm.py
User applications
- Web dashboard
frontend/src/app/page.tsx - REST and WebSocket API
services/api/main.py - Live updates
services/api/ws.py - Guardian workflows
services/guardian/alerts.py - Voice conversations
services/voice/orchestrator.py
Rules and integrations
- Rule evaluation
services/events/engine.py - Rule actions
services/events/actions.py - Home automation MQTT
services/integrations/mqtt/publishers.py - MCP server
services/mcp/server.py
Shared platform
- Application database
shared/database.py - Domain records
shared/models - Runtime settings
shared/app_settings.py - Agent budgets
services/agent/budget.py - Deployment config
shared/config.py - Media storage paths
shared/storage_paths.py
Other components
- IP cameras
Connections 26
- IP cameras → Stream ingestion: sends streams
README.md - Stream ingestion → Perception pipeline: feeds frames
- Stream ingestion → Audio processing: starts audio
services/ingestion/manager.py - Stream ingestion → Live updates: publishes updates
services/ingestion/manager.py - Perception pipeline → Vision descriptions: requests captions
services/perception/pipeline.py - Perception workers → Perception pipeline: runs workers
services/perception/main.py - Perception workers → Incidents and journeys: starts tracker
services/perception/main.py - Perception pipeline → Rule evaluation: evaluates events
services/perception/pipeline.py - Perception pipeline → Text embeddings: creates vectors
services/perception/pipeline.py - Incidents and journeys → Journey tracking: uses journey data
services/perception/incident_tracker.py - Semantic search → Text embeddings: generates vectors
services/search/query.py - Web dashboard → REST and WebSocket API: uses API
- REST and WebSocket API → Ask agent: serves agent requests
services/api/main.py - REST and WebSocket API → Guardian workflows: serves Guardian routes
- REST and WebSocket API → Live updates: hosts sockets
services/api/main.py - Ask agent → Semantic search: answers footage queries
- Rule evaluation → Rule actions: dispatches actions
services/events/engine.py - Rule actions → Home automation MQTT: publishes device actions
services/integrations/mqtt/publishers.py - MCP server → Ask agent: exposes agent tools
services/mcp/server.py - Perception pipeline → Application database: stores observations
services/perception/pipeline.py - Application database → Domain records: maps records
shared/models/__init__.py - Runtime settings → Application database: reads and writes
shared/app_settings.py - Agent budgets → Ask agent: limits usage
- Deployment config → Application database: configures connection
shared/database.py - Media storage paths → Runtime settings: reads override
shared/storage_paths.py - Stream ingestion → Media storage paths: resolves recording roots
services/ingestion/manager.py