Metic

What is Metic about?

Metic provides an all‑in‑one toolkit that automatically creates espresso profiles, analyses shot data and offers AI coaching for the Meticulous Espresso machine. It combines a web UI, REST API, MQTT bridge and optional Home Assistant integration, all delivered as a single Docker container.

How to use Metic?

1. Install Docker and Docker Compose.
2. Pull the container (docker pull ghcr.io/hessius/meticai:v2.0.6) or run the one‑line installer script.
3. Open http://<SERVER_IP>:3550 in a browser.
4. Upload a coffee‑bag photo or type a description, click Create Profile, and the generated recipe is sent to the machine.
5. For automation, call the /api/analyze_and_profile endpoint via curl or integrate through MQTT/Home Assistant.

Key Features

• Automatic espresso profile generation from images or text.
• Detailed extraction guidance (dose, grind, temperature, pressure ramps).
• Real‑time control center with live telemetry via MQTT.
• REST API and Home Assistant MQTT bridge for automation.
• Mobile‑friendly React UI built with shadcn/ui.
• Optional Tailscale remote access and Watchtower auto‑updates.
• iOS Shortcuts for one‑tap brewing.

Use Cases

• Coffee enthusiasts who want AI‑driven recipes without manual calculations.
• Baristas looking to store and compare multiple extraction profiles.
• Home automation setups that trigger pre‑heating, brewing or notifications via Home Assistant.
• Developers building custom integrations with the exposed FastAPI endpoints.

FAQ

Q: What hardware is required? A: A Meticulous Espresso machine on the same network and any device that can run Docker (Raspberry Pi, PC, Mac, etc.).

Q: Is an internet connection needed? A: Only for contacting the Google Gemini API; the core services run locally.

Q: Can I run Metic without Docker? A: The project is distributed as a Docker image; running it directly would require replicating the internal services manually.

Q: How are updates applied? A: With Watchtower enabled updates are pulled every 6 hours; otherwise run docker compose pull && docker compose up -d.

Q: Where is my data stored? A: All profile data lives in Docker volumes on the host, keeping it private unless you expose it.

Metic

All-in-one toolkit for the Meticulous Espresso Machine

Create, profile and understand your espresso. 1. Take a photo or describe your coffee. Get a perfect espresso profile. Automatically. 2. Understand your profiles, shot graphs by enabling shot comparison, analysis and AI-coaching

Get Started • Features • Web Interface • API

---

🎯 What is Metic?

When I got my Meticulous, after a loooong wait, I was overwhelmed with the options — dialing in was no longer just adjusting grind size, the potential was (and is) basically limitless — my knowledge and time not so.

Metic is a growing set of AI tools to help you get the most out of your Meticulous Espresso machine. Among other things it lets you:

• 🧠 Automatically create espresso profiles tailored to your preferences and coffee at hand
• 📊 Understand your espresso profiles and shot data like never before
• 🔬 Get AI coaching to improve your technique
• ☕️ Unleash your Meticulous — no more guesswork, just great espresso

✨ What It Does

For Everyone

• 🌐 Beautiful Web Interface - Upload photos or describe preferences from any device
• 📱 Mobile Friendly - Works perfectly on your phone's browser
• 🎨 Creative Recipe Names - Like "Slow-Mo Blossom" and "Choco-Lot Going On"
• 💬 Natural Language - Just describe what you want in plain English
• 🤖 Fully Automatic - From input to machine, no steps in between

For Coffee Enthusiasts

• 🎯 Advanced Profiling - Multi-stage extraction, blooming, pressure ramping
• 📊 Detailed Guidance - Dose, grind, temperature recommendations
• 🔬 Expert Knowledge - Explanations of why each profile works
• ⚡️ Modern Techniques - Turbo shots, flow profiling, and more

For Power Users

• 🔌 REST API - Integrate with any automation system
• 🏠 Home Assistant - MQTT bridge for HA automations and entities
• 🐳 Single Docker Container - Simple deployment and updates
• 🔓 Open Source - Customize and extend as you like
• 🔄 Auto Updates - Optional Watchtower integration

Additional Features

• 📱 iOS Shortcuts - One-tap brewing from your iPhone
• 🌍 Remote Access - Optional Tailscale integration
• 🔐 Secure - Self-hosted means your data stays private
• 🎨 Modern UI - Built with React and shadcn/ui for a polished experience

🚀 Quick Start

What You Need

• ☑️ A Meticulous Espresso Machine (connected to your network)
• ☑️ A server to run Metic (Raspberry Pi, Mac, Linux, or Windows with Docker)
• ☑️ A free Google Gemini API key → Get yours here (takes 30 seconds)

Installation (5 minutes)

Prerequisites: Docker and Docker Compose (Get Docker)

Linux / macOS:

Quick Install:

curl -fsSL https://raw.githubusercontent.com/hessius/Metic/main/scripts/install.sh | bash

Docker:

docker pull ghcr.io/hessius/meticai:v2.0.6

Upgrading from v1.x:

curl -fsSL https://raw.githubusercontent.com/hessius/Metic/main/scripts/migrate-to-unified.sh | bash

macOS / Windows: Docker Desktop is required. See Docker Desktop for Mac or Docker Desktop for Windows.

Note: The macOS .app installer and Windows PowerShell installer were deprecated in v2.4.0. Use the Docker-based installation above for all platforms.

After Installation

Open http://YOUR_SERVER_IP:3550 in any browser to access the web interface!

Need Help?

• 📖 API Reference
• 🔄 Updating & Migration
• 🌐 Remote Access (Tailscale)
• 🏠 Home Assistant Integration
• 📱 iOS Shortcuts
• 🔧 Troubleshooting

📱 Using Metic

Web Interface (Recommended)

The web interface is the easiest and most powerful way to use Metic. Simply open http://YOUR_SERVER_IP:3550 in any browser.

Create a profile in 3 steps:

1. Upload a photo of your coffee bag, or describe what you want - like "bold and chocolatey" or "light and fruity"
2. Click Create Profile
3. ✨ Done! The recipe is now on your machine

The web interface shows real-time status, analysis results, and generated profiles with full details. It works perfectly on mobile browsers too!

API Examples

For automation and integration:

With a photo:

curl -X POST http://YOUR_IP:3550/api/analyze_and_profile \
  -F "file=@coffee_bag.jpg"

With text preferences:

curl -X POST http://YOUR_IP:3550/api/analyze_and_profile \
  -F "user_prefs=Bold and chocolatey"

With both:

curl -X POST http://YOUR_IP:3550/api/analyze_and_profile \
  -F "file=@coffee_bag.jpg" \
  -F "user_prefs=Traditional extraction"

→ Full API documentation

iOS Shortcuts

For power users who want one-tap brewing from their iPhone, you can create custom shortcuts.

→ iOS Shortcuts setup guide

🎛️ Control Center

Metic includes a real-time Control Center powered by the meticulous-addon MQTT bridge:

• Live telemetry — Real-time pressure, flow, weight, and temperature gauges
• Machine control — Preheat, tare, purge, abort, brightness, sounds, and more
• Live Shot View — Watch your extraction in real-time with live charts
• Auto-detection — Automatically detects when a shot starts and prompts you to watch
• Last Shot Banner — After a shot, offers one-tap analysis with AI coaching
• Home Assistant — MQTT bridge enables auto-discovery of 24 sensors + 11 commands in HA

The Control Center appears as a side panel on desktop and a full page on mobile. Enable it in Settings → Control Center → MQTT Bridge.

Home Assistant Integration

When the MQTT bridge is enabled, your Meticulous machine is automatically discoverable in Home Assistant.

1. Start Metic with the Home Assistant overlay:

   docker compose -f docker-compose.yml -f docker-compose.homeassistant.yml up -d
   

2. In HA, add the MQTT integration and point it to your Metic server's IP on port 1883
3. This enables automations like "notify me when my shot is done" or "preheat at 7am on weekdays"

→ Full Home Assistant integration guide

🔄 Updating Metic

cd ~/Metic
docker compose pull
docker compose up -d

With Watchtower enabled, updates happen automatically every 6 hours.

Manage Addons After Install

You can enable or disable optional addons at any time (Watchtower, Tailscale, Home Assistant MQTT) without re-running the full installer.

Linux/macOS:

cd ~/Metic
bash scripts/addons.sh

Windows PowerShell:

cd $HOME/Metic
powershell -ExecutionPolicy Bypass -File .\scripts\addons.ps1

Remote one-liner (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/hessius/Metic/main/scripts/addons.sh | bash

→ Full update guide, migration from v1.x, and troubleshooting

🗑️ Uninstalling Metic

cd ~/Metic
docker compose down -v  # -v removes all volumes and data
rm -rf ~/Metic

Note: To verify volume names before removal, use docker volume ls

🌐 Optional: Remote Access with Tailscale

Access Metic from anywhere using Tailscale:

1. Get an auth key from Tailscale Admin
2. Enable during installation, or add manually:

cd ~/Metic
echo "TAILSCALE_AUTHKEY=your_key_here" >> .env
docker compose -f docker-compose.yml -f docker-compose.tailscale.yml up -d

Important: Both your Metic server and the device you're accessing it from must have Tailscale installed and connected to the same account. See the full Tailscale setup guide for HTTPS setup, troubleshooting, and more.

🏗️ Architecture

Metic v2.0 runs as a single unified container with five internal services managed by s6-overlay:

┌──────────────────────────────────────────────────────────────┐
│                      Metic Container                       │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                    nginx (:3550)                       │  │
│  │             Web UI + API Reverse Proxy                 │  │
│  └────────────────────────────────────────────────────────┘  │
│                           │                                  │
│       ┌───────────────────┼───────────────┐                  │
│       ▼                   ▼               ▼                  │
│  ┌──────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  Server  │  │ MCP Server  │  │ Gemini CLI  │             │
│  │ (FastAPI) │  │(Meticulous) │  │    (AI)     │             │
│  │  :8000   │  │   :8080     │  │             │             │
│  └──────────┘  └─────────────┘  └─────────────┘             │
│       │                                                      │
│       │ MQTT                                                 │
│       ▼                                                      │
│  ┌──────────┐  ┌─────────────────┐                           │
│  │Mosquitto │◄─│Meticulous Bridge│◄── Machine (Socket.IO)    │
│  │  :1883   │  │  (MQTT Bridge)  │                           │
│  └──────────┘  └─────────────────┘                           │
└──────────────────────────────────────────────────────────────┘

Real-time telemetry: The meticulous-addon bridge connects to your machine via Socket.IO and publishes live sensor data (pressure, flow, weight, temperature) to the internal MQTT broker. The FastAPI server subscribes and pushes updates to the web UI via WebSocket.

Optional sidecars:

• Tailscale - Secure remote access
• Watchtower - Automatic container updates

🛠️ Troubleshooting

Viewing Logs

# Container logs (stdout)
docker logs meticai -f

# Structured logs via API (last 100 entries, filterable by level)
curl http://<SERVER_IP>:3550/api/logs
curl "http://<SERVER_IP>:3550/api/logs?level=ERROR&lines=200"

# Restart a single service
docker exec meticai s6-svc -r /run/service/server

Container won't start

# Check logs
cd ~/Metic && docker compose logs -f

# Check container status
docker compose ps

Can't connect to Meticulous machine

1. Verify the machine is on and connected to your network
2. Check the IP address in your .env file
3. Try using the IP address instead of meticulous.local

API returns errors

# Check relay logs specifically
docker compose logs meticai | grep -i error

Reset everything

cd ~/Metic
docker compose down -v  # -v removes volumes
docker compose pull
docker compose up -d

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Meticulous for creating an amazing machine
• Google Gemini for AI capabilities
• pyMeticulous by Meticulous — official Python client for the Meticulous API
• meticulous-mcp by @twchad — MCP server for machine profile management
• meticulous-addon by @nickwilsonr — MQTT bridge for real-time telemetry and Home Assistant integration

---

Runs on pyMeticulous, meticulous-mcp, meticulous-addon, and caffeine ☕

Made with ❤️ by @hessius