MyHouse OS

Smart home operating system with API backend and Dashboard frontend.

Quick Start

Windows

start.bat

Linux / macOS

chmod +x start.sh
./start.sh

Manual

docker compose up -d

Services

Service	URL	Description
Dashboard	http://localhost:8080	Web interface
API	http://localhost:3000	REST API
API Docs	http://localhost:3000/swagger	Swagger documentation
MCP Server	http://localhost:3001/mcp	AI integration (Claude, etc.)

Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                            MyHouse OS                                 │
├─────────────────┬─────────────────┬─────────────────┬─────────────────┤
│   Dashboard     │      API        │   MCP Server    │    Database     │
│   (Next.js)     │    (Elysia)     │   (AI Tools)    │  (PostgreSQL)   │
│   Port 8080     │    Port 3000    │    Port 3001    │    Port 5432    │
└─────────────────┴─────────────────┴─────────────────┴─────────────────┘

Docker Images

Images are automatically built from their respective repositories:

• API: ghcr.io/myhouse-os/api
• Dashboard: ghcr.io/myhouse-os/dashboard

Commands

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f

# Update to latest images
docker compose pull && docker compose up -d

# Full reset (removes data)
docker compose down -v

Configuration

API Environment Variables

Variable	Default	Description
DATABASE_URL	postgresql://root:root@db:5432/myhouse	PostgreSQL connection string
ENCRYPTION_KEY	MySuperSecretPasswordFixed123!	Encryption key for tokens
ENCRYPTION_SALT	MyFixedSalt	Salt for encryption
PORT_BUN_SERVER	3000	API port
PORT_WEB_SERVER	8080	Web server port
MCP_PORT	3001	MCP server port
API_BASE_URL	http://localhost:3000	API base URL (used by MCP)

Dashboard Environment Variables (Build-time)

These variables are baked into the Docker image at build time.

Variable	Default	Description
NEXT_PUBLIC_API_URL	http://localhost:3000	API URL
NEXT_PUBLIC_WS_URL	ws://localhost:3000/ws	WebSocket URL
NEXT_PUBLIC_AUTH_ID	root	Default auth client ID
NEXT_PUBLIC_AUTH_TOKEN	root	Default auth token
NEXT_PUBLIC_LOGIN_USERNAME	root	Login username
NEXT_PUBLIC_LOGIN_PASSWORD	root	Login password
NEXT_PUBLIC_SERVER_IP	192.168.4.1	ESP32 server IP
NEXT_PUBLIC_CLIENT1_IP	192.168.4.3	ESP32 client 1 IP
NEXT_PUBLIC_CLIENT2_IP	192.168.4.4	ESP32 client 2 IP

Database Environment Variables

Variable	Default	Description
POSTGRES_USER	root	Database user
POSTGRES_PASSWORD	root	Database password
POSTGRES_DB	myhouse	Database name

Note: Dashboard variables are pre-built with localhost values. For remote deployment, rebuild the Dashboard image with custom NEXT_PUBLIC_* variables.

Releases

New releases are automatically created when API or Dashboard images are updated. Check the Releases page for the latest version.

MCP Server (AI Integration)

The API includes a built-in MCP (Model Context Protocol) server on port 3001, allowing AI assistants like Claude to control your smart home.

Available Tools

Tool	Description
get_home_state	Get current state (temperature, light, door, heating)
get_history	Get event history (limit parameter)
toggle_light	Toggle light on/off
toggle_door	Open/close door
toggle_heat	Turn heating on/off
set_temperature	Set temperature reading

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "myhouse": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "CLIENT_ID:CLIENT_TOKEN"
      }
    }
  }
}

Endpoints

Endpoint	Description
http://localhost:3001/mcp	MCP protocol endpoint (requires auth)
http://localhost:3001/health	Health check

ESP32 Simulator

The startup scripts include an interactive ESP32 simulator to test the API without physical hardware.

Features

Option	Action
1	Set Temperature
2	Toggle Light
3	Toggle Heating
4	Toggle Door
5	Get System Status
6	Custom API Request
0	Exit

Manual Launch

# Requires Bun installed
bun scripts/esp-simulator.js

# With custom settings
API_URL=http://localhost:3000 AUTH_ID=root AUTH_TOKEN=root bun scripts/esp-simulator.js

What it does

The simulator sends real HTTP requests to the API, simulating an ESP32 device. You can:

• Control lights, heating, and doors
• Set temperature readings
• View the current home state
• Make custom API requests

When you exit the simulator (option 0 or Ctrl+C), you'll be asked if you want to stop the Docker containers.

Related Repositories

• API - Backend service (Bun + Elysia)
• Dashboard - Frontend (Next.js + React)