Skip to content

Latest commit

 

History

History
176 lines (123 loc) · 4.88 KB

02-install.md

File metadata and controls

176 lines (123 loc) · 4.88 KB

Installing Uschi

There are three ways to install Uschi. All three start from the same ./install.sh — the wizard asks which one you want.


Prerequisites (all tracks)

You need:

  • Docker with Docker Compose v2 (docker compose ..., not the legacy docker-compose).
  • git, curl, and openssl on your PATH.
  • 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.


Track 1 — Local

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 --local

When 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.


Track 2 — Server (with public TLS)

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 80 and 443 open (for Caddy), plus TCP 7881 and UDP 50000-50200 open (for LiveKit's WebRTC fallback).
git clone https://github.com/tomgoeck/uschi_ai.git
cd uschi_ai
./install.sh --server

The 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.


Track 3 — Raspberry Pi smart speaker

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).

Hardware

  • 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.

Wake word

Pi wake-word detection uses Picovoice Porcupine, which is free for personal use. You'll need:

  1. A Picovoice account (free signup) at console.picovoice.ai.
  2. Your AccessKey from the console.
  3. A wake-word model (.ppn file). 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.

Install

On the Pi:

git clone https://github.com/tomgoeck/uschi_ai.git
cd uschi_ai
./install.sh --pi

The wizard will ask for:

  • Your main server's LiveKit URL (e.g. ws://uschi-server.local:7880).
  • The LIVEKIT_API_KEY and LIVEKIT_API_SECRET from your server's .env.
  • Your Picovoice AccessKey.
  • The path to your .ppn wake-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.py

Say your wake word — Uschi answers.

Autostart on boot

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 uschi

The service file expects the repo to be at /home/pi/uschi_ai. Edit it if your checkout is somewhere else.

Audio device tuning

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.


Reconfiguring later

To change a single value in .env (e.g. swap to a different Gemini voice), re-run:

./install.sh --reconfig

The wizard reads existing values, lets you change just the ones you want, and restarts the relevant containers.


Next: 03-customize.md — make Uschi yours.