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