There are three ways to install Uschi. All three start from the same
./install.sh — the wizard asks which one you want.
You need:
- Docker with Docker Compose v2 (
docker compose ..., not the legacydocker-compose). git,curl, andopensslon yourPATH.- A free Google Gemini API key. Get one at https://aistudio.google.com/apikey. No credit card is required for the free tier.
- A working OpenClaw install on your machine. The wizard will hand off to OpenClaw's own setup if it isn't configured yet. See https://openclaw.dev/install.
That's it.
The "I just want to try it on my laptop" path.
git clone https://github.com/tomgoeck/uschi_ai.git
cd uschi_ai
./install.sh --localWhen the wizard finishes, open http://localhost:8484 and click the talk
button. The dashboard is protected by HTTP Basic auth — username uschi,
password is printed at the end of the install (and lives in .env as
DASHBOARD_PASSWORD).
To stop everything: docker compose down.
To start it again later: docker compose up -d.
To view logs: docker compose logs -f.
The full stack uses about 1.5 GB of RAM at idle. The Gemini API call burns your free-tier quota only while you're actually talking.
For when you want your household to share Uschi over the internet.
You need:
- A server with a public IPv4 address.
- A domain name pointing at that server (an A record). Caddy will get a Let's Encrypt cert automatically.
- Inbound TCP
80and443open (for Caddy), plus TCP7881and UDP50000-50200open (for LiveKit's WebRTC fallback).
git clone https://github.com/tomgoeck/uschi_ai.git
cd uschi_ai
./install.sh --serverThe wizard will ask for your domain (e.g. uschi.example.com) and your
contact email for Let's Encrypt. It writes both into .env and adds the
Caddy override compose file to the stack.
After the install, point your browser at https://your-domain and log in.
Caddy handles TLS for you — no certificate dance.
Security note. The dashboard ships with HTTP Basic auth. That's fine for personal use, but if you're putting Uschi on the open internet, also consider putting it behind a VPN (Tailscale, WireGuard) or a real auth proxy. Basic auth over TLS is okay; basic auth without TLS is not.
Turn a Pi into a "Hey Uschi" smart speaker.
This track installs only the Pi client. You also need the main Uschi stack running somewhere reachable on your network — usually on a separate machine (Track 1 or Track 2).
- A Raspberry Pi 4 (2 GB or more) running Raspberry Pi OS Lite (64-bit).
- A USB microphone and a USB or 3.5mm speaker. A ReSpeaker 2-Mics Pi HAT works well if you want something tidier.
Pi wake-word detection uses Picovoice Porcupine, which is free for personal use. You'll need:
- A Picovoice account (free signup) at console.picovoice.ai.
- Your AccessKey from the console.
- A wake-word model (
.ppnfile). You can use the default keywords that ship with Porcupine, or train a custom one — the console has a wake-word trainer.
Drop the .ppn file into pi-client/ and remember the path.
On the Pi:
git clone https://github.com/tomgoeck/uschi_ai.git
cd uschi_ai
./install.sh --piThe wizard will ask for:
- Your main server's LiveKit URL (e.g.
ws://uschi-server.local:7880). - The
LIVEKIT_API_KEYandLIVEKIT_API_SECRETfrom your server's.env. - Your Picovoice AccessKey.
- The path to your
.ppnwake-word file.
Then install the Python deps:
cd pi-client
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python uschi_pi.pySay your wake word — Uschi answers.
To run the Pi client as a systemd service so it survives reboots:
sudo cp pi-client/uschi.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now uschi
sudo systemctl status uschiThe service file expects the repo to be at /home/pi/uschi_ai. Edit it if your
checkout is somewhere else.
If your mic and speaker show up at unexpected ALSA indices, set them
explicitly via the AUDIODEV env var or with pulseaudio defaults. The
client uses PyAudio's default input/output devices.
To change a single value in .env (e.g. swap to a different Gemini voice),
re-run:
./install.sh --reconfigThe wizard reads existing values, lets you change just the ones you want, and restarts the relevant containers.
Next: 03-customize.md — make Uschi yours.