Skip to content

installation guide

Jump to bottom
TranQuiL edited this page Jun 11, 2026 · 1 revision

🚀 Installation Guide

Welcome to the installation guide for Grocy: The God-Tier Overhaul.

Because this overhaul completely transforms how Home Assistant interacts with Grocy, the installation is split into two mandatory parts: the Python Backend (the brain) and the Command Center (the face). You must install both for the Optimistic UI and AI features to work.

🛑 Prerequisites

Before you begin, ensure you have the following:

  1. A working Grocy Server: This can be the Home Assistant Add-on, a standalone Docker container, or an LXC container.
  2. HACS (Home Assistant Community Store): Installed and configured in your Home Assistant instance.
  3. Your Grocy API Key: Generated from your Grocy interface (Settings > Manage API keys).

Part 1: Install the Bulletproof Backend

The backend integration handles the "Direct API Strikes" and zero-crash coordinators. The easiest way to install this is via HACS.

1. Add the Custom Repository:

  • Open HACS in your Home Assistant sidebar.
  • Navigate to the Integrations section.
  • Click the three dots (...) in the top right corner and select Custom repositories.
  • Paste this repository URL: https://github.com/DonTranQuiL/Grocy
  • Set the Category to Integration and click Add.

2. Download the Integration:

  • A new card for Grocy will appear in HACS. Click it.
  • Click Download in the bottom right corner.

3. ⚠️ RESTART HOME ASSISTANT ⚠️

  • You MUST restart Home Assistant to load the new Python code. Go to Settings > System > Power button > Restart Home Assistant.

4. Configure the Integration:

  • Go to Settings > Devices & Services.
  • Click + Add Integration and search for Grocy.
  • Enter your Grocy Server URL, Port, and API Key.

Part 2: Install the Command Center (Frontend)

The frontend is the blazing-fast, Optimistic UI card that you will actually interact with.

1. Add the Custom Repository (Again, but for Frontend):

  • Open HACS and navigate to the Frontend section.
  • Click the three dots (...) -> Custom repositories.
  • Paste the exact same URL: https://github.com/DonTranQuiL/Grocy
  • Set the Category to Dashboard and click Add.

2. Download the Card:

  • Locate the Grocy Command Center card in HACS and hit Download.
  • When prompted to reload your browser, click Reload.

3. ⚠️ CLEAR YOUR BROWSER CACHE ⚠️

  • Home Assistant aggressively caches old JavaScript. Press Ctrl + Shift + R (Windows) or Cmd + Shift + R (Mac) to force your browser to load the new custom card. If you are using the mobile app, go to Settings > Companion App > Debugging > Clear Frontend Cache.

(Note: If you prefer manual installation, download grocy-action-card.js from this repository, place it in your /config/www/ folder, and add /local/grocy-action-card.js as a JavaScript Module in your Dashboard Resources).

Part 3: Add to Your Dashboard

Now that both the brain and the face are installed, it's time to put it on your wall!

  1. Go to your Home Assistant Overview/Dashboard.
  2. Click the Pencil Icon in the top right to edit the dashboard.
  3. Click + Add Card.
  4. Scroll all the way to the bottom and select Manual.
  5. Paste the following YAML configuration:
type: custom:grocy-action-card

Clone this wiki locally