AI Stack

Local AI operator stack for Windows 11 / WSL2 with honest architecture, one operator CLI, and generated operational artifacts.

AI Stack is a public operator-focused repository for running a practical local AI environment with LiteLLM, Ollama, Open WebUI, Compose profiles, and repeatable PowerShell / shell workflows.

Public Review Path

• Architecture
• Operations
• Release notes and packaging
• Known limitations
• Dashboard artifact
• Screenshots plan

What It Demonstrates

• Windows-first local AI operations with WSL2-aware tooling.
• One honest control plane instead of fake platform abstraction.
• Operator validation, smoke checks, backups, and generated self-check artifacts.
• Public documentation for architecture, operations, and troubleshooting.

Quick Start

Security Note

Do not commit your .env file to GitHub or any public repository. Use .env.sample for example values and store real secrets in secure storage (Windows Credential Manager, environment variables, or a secret manager). The installer will generate local secrets for testing, but you must rotate cloud API keys before publishing.

WSL2 / Linux Shell

chmod +x install.sh stack.sh
./install.sh
./stack.sh start core
./stack.sh doctor
./stack.sh smoke

PowerShell

.\install-windows.ps1
.\stack.ps1 start core
.\stack.ps1 doctor
.\stack.ps1 smoke

For UI:

./stack.sh start ui

.\stack.ps1 start ui

What Is Actually Supported

• Compose profiles: hot, warm, aider
• Logical operator modules: core, ui, coding
• Real services:
  • postgres
  • litellm
  • open-webui
  • aider as on-demand helper
  • ollama as host dependency
• Generated operational artifacts:
  • dashboards/index.html
  • SELF_CHECK.txt

Operator Commands

./stack.sh start core
./stack.sh stop
./stack.sh restart ui
./stack.sh doctor
./stack.sh status
./stack.sh logs litellm
./stack.sh smoke
./stack.sh validate
./stack.sh backup
./stack.sh refresh

PowerShell:

.\stack.ps1 start core
.\stack.ps1 stop
.\stack.ps1 restart ui
.\stack.ps1 doctor
.\stack.ps1 status
.\stack.ps1 logs litellm
.\stack.ps1 smoke
.\stack.ps1 validate
.\stack.ps1 backup
.\stack.ps1 refresh

Modules and Profiles

• core maps to compose profile hot: postgres + litellm
• ui maps to warm: adds open-webui
• coding maps to aider: on-demand helper on top of the core module

This is an operator module layer. Compose remains simple and honest without inventing unnecessary profile sprawl.

Runtime Model Routing

LiteLLM aliases in litellm-config.yaml:

• openai-gpt4
• claude-sonnet
• claude-4-opus
• gemini-pro
• mistral-openrouter
• ollama-coder-local

If a cloud key is missing, the alias stays configured but non-functional. doctor is expected to surface that explicitly.

Source of Truth

• Architecture truth layer: docs/ARCHITECTURE.md
• Operations handbook: docs/OPERATIONS.md
• Troubleshooting matrix: docs/TROUBLESHOOTING.md
• Known limitations: docs/KNOWN_LIMITATIONS.md
• Future module slots: docs/EXTENSIBILITY.md
• Release discipline: docs/RELEASE.md

Dashboard and Self-Check

• Dashboard: dashboards/index.html
• Self-check report: SELF_CHECK.txt

Both artifacts are generated by:

./stack.sh refresh

или:

.\stack.ps1 refresh