Overview
greenhouse monitors soil moisture, temperature, humidity, and light from Tuya-compatible sensors and makes smart irrigation decisions based on evidence-based plant care data. It learns from past irrigation cycles to detect efficiency issues, blocked drips, and unresolvable plant conflicts.
uv sync
uv run greenhouse-server # start REST API + web UI
uv run greenhouse check --all # check all clusters
How it decides
- Reads sensor data from Tuya Cloud, synced to a local SQLite archive.
- Decides using a typed
IrrigationDecision pipeline: cooldown check, stress detection, multi-sensor conflict resolution, trend analysis, evidence-based moisture targets. Every evaluation produces a structured Reason trail and is persisted whether or not it was acted on.
- Acts by controlling Tuya irrigators over local protocol v3.5.
- Learns — builds per-plant absorption/drainage profiles; raises advisory alerts (blocked drip, rapid drainage, chronic underwatering, unresolvable conflict). Learning never blocks decisions.
- Persists sensor readings, irrigation events, decision logs, alerts, and activity events in a local SQLite archive. Tuya Cloud is the live source; SQLite is the permanent record.
Interfaces — four ways in, one source of truth
| Interface | URL | Notes |
|---|
| JSON REST API | /api/v1 | Authoritative entry point. OpenAPI docs at /docs. |
| Web UI | / | HTMX + Jinja2 server-rendered. Shares service layer with the API. |
| CLI | greenhouse | Thin httpx client against /api/v1. No DB access. |
| MCP server | /mcp | Every /api/v1 endpoint as an MCP tool via fastapi-mcp. Auth deferred — localhost-only. |
Stop the server and all four go dark. Anything new the CLI or an MCP tool should be able to do must first exist as an API endpoint.
Warning: MCP gives a connected LLM the ability to actuate physical irrigation hardware (/clusters/{id}/irrigate, /irrigators/{id}/start, etc.). Keep the server localhost-only until auth is added.
Getting Started
Prerequisites
Installation
git clone https://github.com/giocaizzi/greenhouse.git
cd greenhouse
uv sync
Configuration
Copy .env.example and fill in your Tuya credentials:
cp .env.example .env
| Variable | Required | Description |
|---|
TUYA_CLIENT_ID | Yes | Tuya IoT Platform client ID |
TUYA_CLIENT_SECRET | Yes | Tuya IoT Platform client secret |
TUYA_REGION | Yes | eu, us, cn, or in |
IRRIGATION_DB_URL | No | SQLite URL (default: sqlite:///data/irrigation.db) |
IRRIGATION_SERVER_URL | No | CLI server URL (default: http://localhost:8000) |
Usage
# Start the server (API at /api/v1, web UI at /)
uv run greenhouse-server
# Set up a cluster
uv run greenhouse cluster add "Living Room" --environment indoor
uv run greenhouse plant add "Monstera deliciosa" --cluster 1
uv run greenhouse sensor add --cluster 1 --device-id YOUR_DEVICE_ID --name "Monstera Sensor" --type soil_moisture
# Operations
uv run greenhouse status 1 # full cluster overview
uv run greenhouse irrigate 1 # smart irrigation pipeline
uv run greenhouse check --all # check all clusters + alerts
uv run greenhouse learn 1 # learning report
uv run greenhouse stats 1 --days 7 # irrigation statistics
Same data is also available via:
- Web UI — open
http://localhost:8000/ for the HTMX dashboard (clusters, per-plant charts, irrigators, history, scheduler, alerts, health).
- REST API —
http://localhost:8000/api/v1/...; OpenAPI docs at http://localhost:8000/docs.
- MCP server —
http://localhost:8000/mcp (streamable HTTP). Point an MCP client (e.g. Claude Desktop) at it and every API endpoint shows up as a tool.
Development
