GPT Home on a Raspberry Pi: a self-hosted alternative to Nest Hub and Alexa

What GPT Home replaces, and for whom

Commercial smart speakers route your voice through a vendor account and expose a fixed set of skills. GPT Home takes the opposite position: the assistant runs on hardware you own, and the model behind it is whatever LiteLLM can reach. The README frames the project as "a better Google Nest Hub or Amazon Alexa home assistant" and lists the intended jobs: weather, alarms, reminders, calendar, to-do list, general knowledge, translation, music, lights, and games. That list matters more than the framing, because it tells you the project is aiming at daily household chores rather than at being a general agent platform.

The audience is narrow and specific. You need a Raspberry Pi, a speaker, a microphone, and a willingness to run a shell script and edit a .env file. The README's parts list is a single builder's shopping list, not a supported hardware matrix, and it prices a Pi 4B at $50 to $70, a mini speaker at $18, a USB microphone at $8, and a 128GB microSD card at $13. The author also states plainly that any Linux system should work thanks to Docker, but that only the versions in the compatibility table are vouched for. That sentence is the whole adoption decision in miniature.

How the Docker stack fits together

The repository ships a docker-compose.yml that defines the runtime as separate services. A db service runs pgvector/pgvector:0.8.1-pg18-trixie with a healthcheck built on pg_isready against 127.0.0.1 on port 5432, and persists data in a named volume mounted at /var/lib/postgresql/data. An nginx service runs nginx:alpine, mounts contrib/nginx.conf read-only, and healthchecks itself with wget against http://127.0.0.1/health. A frontend service is pinned to platform linux/arm64, exposes port 3000, and only starts under the prod profile. Every one of these services uses network_mode: host, so there is no Docker bridge network to reason about and no port mapping to translate.

The application layer is Python, with a Node.js and React frontend behind nginx. The README names LiteLLM and LangGraph as the core libraries, and the topics list adds fastapi, langmem, langchain and speech-recognition. LiteLLM is the provider abstraction: the .env.example documents support for OpenAI, Anthropic, Google, Cohere, Azure and, in its words, 100+ more. LangGraph and langmem sit behind the persistent memory feature, and the pgvector image is the storage layer that makes semantic recall possible. The .env.example asks for an EMBEDDING_MODEL in provider:model form, with openai:text-embedding-3-small and EMBEDDING_DIMS=1536 as the defaults.

One design consequence is worth stating directly. Because the database, nginx and the frontend all bind to the host network, this stack assumes it owns the machine. Running it alongside another web server on port 80 or another PostgreSQL on 5432 will collide. That is a reasonable choice for a dedicated Pi and a poor one for a shared box.

Installing GPT Home on a Raspberry Pi

The README's TL;DR for production is two steps. The first is the setup script, fetched from the main branch and piped into bash with the --no-build flag, which the README describes as installing system dependencies such as Docker and time sync automatically:

curl -s https://raw.githubusercontent.com/judahpaul16/gpt-home/main/contrib/setup.sh | \
    bash -s -- --no-build

The second step is the API key, and the README marks it as required. It copies .env.example to .env, rewrites the LITELLM_API_KEY line with sed, then restarts the stack:

cd ~/gpt-home
cp .env.example .env
sed -i 's/^LITELLM_API_KEY=$/LITELLM_API_KEY=your-api-key-here/' .env
docker compose down && docker compose up -d

The README also notes that the key can be set later through the web interface at gpt-home.local/settings, which points to a LiteLLM provider page for the full list. To confirm the assistant is actually running, the README suggests following the logs:

docker compose logs -f

For development the path is different: clone the repository, copy .env.example to .env, edit it with your keys, then start the dev profile with hot reload.

git clone https://github.com/judahpaul16/gpt-home.git
cd gpt-home
cp .env.example .env
COMPOSE_PROFILES=dev docker compose up

The README says the dev environment is reachable at http://localhost, where nginx routes to the frontend and the API. Note the two paths are not interchangeable: the production script installs system dependencies, while the development path assumes you already have Docker and just want the profiles.

The Raspberry Pi constraints the compatibility table sets

The specifications table is where the project's real ceiling lives. Minimum is a Raspberry Pi Zero 2 W with a quad-core Cortex-A53 at 1GHz, 512MB of RAM, a 16GB microSD card, and Raspberry Pi OS Lite 64-bit. Recommended is a Pi 4B or 5 with a Cortex-A72 at 1.5GHz or better, 1GB or more of RAM, 32GB or more of storage, and Ubuntu Server 64-bit.

The gap between those two columns is the story. A 512MB board has to hold PostgreSQL with pgvector, nginx, a Python backend, a React frontend served through nginx, and whatever LiteLLM pulls in. The README does not publish memory figures for the running stack, so treat the minimum column as a floor the author believes is bootable rather than a configuration anyone has described as comfortable. If you are buying hardware for this, the recommended column is the honest target.

Two more constraints are easy to miss. First, the frontend image is built for linux/arm64 and the compose file pins platform: linux/arm64, so x86 hosts are outside the documented path even though the README says any Linux system should theoretically work. Second, audio is not abstracted. The README states you can use any plug-and-play USB or 3.5mm speaker or microphone as long as ALSA or PortAudio supports it. That is a real dependency on kernel-level audio support, and it is the most likely place for a first build to stall.

Integrations, and the ones that are not finished

The integrations table is marked with checkmarks and one empty box. Confirmed entries include OpenAI, Spotify, Philips Hue, OpenWeatherMap, Open-Meteo, alarms, reminders, CalDAV calendar, LiteLLM, LangGraph, persistent memory, and display support. Zigbee2MQTT is the single unchecked item.

That unchecked box is worth taking at face value: Zigbee2MQTT is not listed as available, so anyone planning to control Zigbee devices directly through this assistant should assume they cannot, and should look at whether Philips Hue covers their hardware instead. The same caution applies to the Spotify entry. The .env.example sets SPOTIFY_BROKER_URL to https://gpt-home.judahpaul.com, which means Spotify control depends on a broker endpoint the author operates rather than on a purely local integration. That is the one part of the stack with an external dependency outside your house, and the README does not document a self-hosted broker alternative or what happens when that endpoint is unreachable.

Display support is listed as available, and the parts list describes a 3.5 inch PiScreen at 480x320 over SPI with an ILI9486 controller that the setup script auto-detects, alongside a 128x32 I2C display and a 7 inch HDMI touchscreen at 1024x600. The README does not describe what the display renders, so treat it as a supported output with undocumented behaviour.

Where GPT Home is the wrong tool, and what to use instead

The clearest failure mode is the one the README warns about itself. In the schematics section it states, in bold, that you must not connect a battery directly to the Raspberry Pi and should use a UPS or a battery-backed power supply instead, because voltage fluctuations can damage the board. This is a project where a wiring mistake costs you hardware. Anyone who wants to plug a device into a wall and forget it is not the audience.

The second case is the shared machine. Because the compose file uses network_mode: host throughout and binds PostgreSQL to 5432 and nginx to port 80, GPT Home wants a dedicated host. If you already run Home Assistant OS on the same Pi, or any other service on those ports, this stack will conflict with it.

The natural alternative is Home Assistant itself. The difference is architectural rather than cosmetic. Home Assistant is a local automation engine with a device-integration model at its centre: entities, state machines, and automations that run whether or not a network is available. GPT Home is a language-model application that treats integrations as tools the assistant can call. If your goal is deterministic automation that fires at 7am regardless of an API outage, Home Assistant is built for that and GPT Home is not. If your goal is asking a question out loud and having the house answer, Home Assistant's conversational layer is a bolt-on while conversation is the core of GPT Home. The two can coexist conceptually, but not on the same ports.

Licence, maintenance and what an upgrade costs you

GPT Home is licensed GPL-3.0. For a self-hosted household assistant that is unlikely to matter, but if you intend to distribute a modified version, or ship hardware with it preinstalled, the copyleft terms apply to the derivative work. That is a question for a lawyer, not for this article.

Maintenance looks current. The repository is not archived, the last push was on 2026-09-13, and the releases list shows v2.2.0 on 2026-09-13, v2.1.24 on 2026-09-13 and v2.1.23 on 2026-09-12. Three releases across two days is a fast cadence, and it also means the upgrade surface moves quickly. The frontend service pulls ghcr.io/judahpaul16/gpt-home-frontend:latest, so a docker compose pull can change your UI without any version number changing in your own files. If you want reproducible upgrades, pinning that tag is the obvious first move, and the README does not discuss pinning or rollback.

The upgrade cost is otherwise mostly configuration drift. The .env.example is the contract between you and the stack: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, DATABASE_URL, LITELLM_API_KEY, MODEL, EMBEDDING_MODEL, EMBEDDING_DIMS and SPOTIFY_BROKER_URL. When a release adds a key, your existing .env will not have it, and the compose file's defaults will quietly apply instead. Diffing your .env against .env.example after each pull is the cheapest habit this project rewards.

Editorial conclusion

Adopt GPT Home if you already run a Raspberry Pi 4B or 5 with a 64-bit OS, are comfortable reading docker compose logs, and want one assistant spanning weather, alarms, reminders, CalDAV calendar, Spotify and Philips Hue without a vendor account. Skip it if you want a finished consumer device, if your board is a 512MB Pi Zero 2 W, or if you cannot supply a LiteLLM API key, since the README marks that key as required. Before flashing anything, check the compatibility table against your board and OS, confirm your speaker and microphone are supported by ALSA or PortAudio, and read .env.example end to end so you know which integrations you are actually enabling.

Frequently asked questions

Official sources

1. judahpaul16/gpt-home on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases