# Homegrown AI App Demo

> Use when working on, running, stopping, verifying, debugging, or configuring the HomeGrown AI App Demo project, including its Docker Compose stack, FastAPI app, PostgreSQL database, LiteLLM proxy, Prompt Security settings, model cache, provider keys, or custom inference endpoints.

- Skill: `prompt-security/homegrown-ai-app-demo` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add prompt-security/homegrown-ai-app-demo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prompt-security/homegrown-ai-app-demo/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: prompt-security (https://skillmd.com/u/prompt-security)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prompt-security/homegrown-ai-app-demo

---


# HomeGrown AI App Demo

## Overview

Use this skill for project-specific app operations in the HomeGrown AI App Demo repository. It captures the known Docker Compose workflow, verification checks, and inference configuration points for this repo.

## Project Facts

- App directory: the repository root containing `docker-compose.yml`, `app/`, and `litellm/`
- Main services: `app`, `db`, `litellm`
- URLs:
  - Chat UI: `http://localhost:9000`
  - Admin UI: `http://localhost:9000/admin`
  - LiteLLM proxy: `http://localhost:4000`
- **There is no `.env` file and there never will be.** All configuration goes in the `environment:` sections of `docker-compose.yml`, or through the Admin → Settings panel at runtime.
- Default admin credentials and all secrets (encryption key, API keys, etc.) are set directly in `docker-compose.yml`.
- Repo-level LiteLLM model routing lives in `litellm/config.yaml`.
- Provider API keys (OpenAI, Anthropic, Google, Perplexity, OpenRouter) can be set as env vars in `docker-compose.yml` or saved at runtime via **Admin → Settings → LLM API Keys** — runtime-saved keys take precedence and trigger automatic model discovery.

## Helper Script

Prefer the bundled script for routine operations:

```bash
bash .codex/skills/homegrown-ai-app-demo/scripts/manage.sh status
bash .codex/skills/homegrown-ai-app-demo/scripts/manage.sh start
bash .codex/skills/homegrown-ai-app-demo/scripts/manage.sh stop
bash .codex/skills/homegrown-ai-app-demo/scripts/manage.sh verify
bash .codex/skills/homegrown-ai-app-demo/scripts/manage.sh refresh-models
```

Run the helper from anywhere inside the repo. If the repo cannot be discovered from the current directory or script location, set `HOMEGROWN_AI_APP_DIR=/path/to/homegrown-ai-app-demo`.

## Common Workflows

### Start or Restart

1. Check for dirty work before edits: `git status --short`.
2. Run `docker compose up -d --build`.
3. Wait for LiteLLM to finish first-run migrations if needed (~3–5 min on first run).
4. Refresh the app model cache with `POST /admin/refresh-models`.
5. Verify with `docker compose ps`, `GET /health`, `GET /`, `GET /admin`, and authenticated `GET /models`.

### Stop

Run `docker compose stop`, then verify `docker compose ps` shows no project containers running.

### Configure Inference

There are two ways to add models:

**1. LiteLLM config (static)** — add a model entry to `litellm/config.yaml` and set any required API key in the `environment:` section of `docker-compose.yml`. Restart `litellm` and `app`, then refresh the model cache.

**2. Direct provider routing (dynamic)** — save an API key for OpenAI, Anthropic, Google, Perplexity, or OpenRouter in **Admin → Settings → LLM API Keys**. The app queries the provider's `/models` endpoint and adds all available models to the picker automatically as `provider/model-id` (e.g. `openai/gpt-4.1`). These bypass LiteLLM entirely.

For custom OpenAI-compatible endpoints, add the base URL and model ID via `litellm/config.yaml`. Never hardcode API keys in repo files — use `docker-compose.yml` environment sections or the admin Settings panel.

For the project’s local OpenAI-compatible test server, use:

- Host URL: `http://localhost:8081/v1`
- Docker URL: `http://host.docker.internal:8081/v1`
- Current model ID: `huggingface/Qwen3VL-8B-Instruct-F16`
- Env vars: `LOCAL_OPENAI_BASE_URL`, `LOCAL_OPENAI_API_KEY`, `LOCAL_OPENAI_MODEL_IDS`

### Debug

- App logs: `docker compose logs --no-color --tail=120 app`
- LiteLLM logs: `docker compose logs --no-color --tail=160 litellm`
- DB logs: `docker compose logs --no-color --tail=120 db`
- Health: `curl -sS http://localhost:9000/health | python3 -m json.tool`
- LiteLLM models:
  `curl -sS http://localhost:4000/v1/models -H "Authorization: Bearer $(docker compose exec app printenv LITELLM_MASTER_KEY)"`

## Verification Rule

Before saying the app is running, stopped, fixed, or configured, run fresh verification in the current turn and report the actual output state. Use `superpowers:verification-before-completion` when making completion claims.