AI - Local Stack Control

v3.1 — Codename: Ankh of Jah
http://dcos.net

A PySide6 desktop application for orchestrating local AI/ML tool stacks across a 10-layer architecture.

AI Local Stack Control (AI-LSC) provides a unified interface to discover, configure, launch, and manage 140 tools spanning the entire AI software stack — from GPU runtimes and inference engines to agent frameworks, security tooling, and knowledge management.

Features

10-Layer Infrastructure Architecture

Every tool in the registry is classified within a 10-layer taxonomy, giving you a clear mental model of your entire AI stack. Select tools directly from the sidebar — the sidebar is the wizard.

Layer	Tools	Examples
L1 — Host Platform	9	PostgreSQL, MariaDB, Redis, SQLite3, DuckDB, Podman, Docker, Tmux, Git
L2 — Development Environment	7	Python Environment, CuPy, ripgrep, fd, tree-sitter, SST, Unsloth
L3 — GPU Runtimes	3	CUDA Toolkit, NVIDIA Apex, Heretic
L4 — Engines	7	Ollama, llama.cpp, KoboldCPP, Llamafile, TurboLLM, AirLLM, Locally-Uncensored
L5 — Orchestrators	26	vLLM, Ray, LiteLLM Proxy, 9Router Proxy, LangChain, LangFlow, Dify, CrewAI, AutoGen, Wayland AI, +17 more
L6 — Security	6	Keycloak, HashiCorp Vault, Trivy, Fail2Ban, ClamAV, Open Policy Agent
L7 — Observability	8	Btop, Glances, Prometheus, Grafana, Grafana Alloy, Opik, Pulse AI, Latitude
L8 — User Interfaces	16	Open WebUI, AnythingLLM, LibreChat, Flowise, InvokeAI, Forge (A1111), ComfyUI, Dashy, Obsidian, +7 more
L9 — DevOps	33	Terraform, Ansible, Puppet, Pulumi, OpenTofu, AWS CDK, Crossplane, n8n, Aider, Claude Code, OpenHands, +23 more
L10 — Knowledge Management	25	Zotero, Calibre, Paperless-ngx, Logseq, Joplin, ChromaDB, LanceDB, Qdrant, LlamaIndex, +16 more

Sidebar-Integrated Infrastructure Selector

The sidebar doubles as the stack wizard — expand the Infrastructure tree to reveal all 10 layers, each showing its tools with rich-text interface badges (CLI, GUI, Web, Ollama, Docker, MCP, etc.). Toggle checkboxes to stage tools; a debounced compiler (400ms) automatically validates dependencies and writes the compiled pipeline state. No separate popup window needed.

Stack Editor

Visually compose your tool stack using templates, a two-panel flow builder, and dependency validation. Select from 13 pre-configured stack templates, then customize the wiring topology. Lifecycle engine controls let you start, stop, and monitor services directly from the editor.

Active Monitor

Stripped to show only active metrics — real-time system health monitoring focused on the services that are actually running. CPU/memory metrics and per-service status indicators for your live stack.

Pipeline Ticker

A horizontally scrolling status bar at the top of every workspace tab that visualizes the wiring topology of your currently-staged tools in real time. Edges are drawn from the live STACK_WIRINGS data: provider ──interface──▶ consumer, with arrow color encoding the interface type (blue = openai_api, green = vector, orange = redis_pubsub, purple = postgresql, teal = http_api, etc.). Orphan tools — active but with no wiring to any other active tool — are flagged in red with a warning prefix so you can immediately see disconnected tools. Hover to pause the scroll; click any tool pill to jump to that tool's row.

Stack Templates

Get started quickly with 13 pre-configured stack templates:

• Claude Code Setup — Full Claude Code ecosystem (11 tools)
• Free Claude Code — Minimal Claude Code setup (4 tools)
• SaaS Integrations — Production deployment stack (12 tools)
• Local LLM Lab — Self-hosted LLM playground (10 tools)
• Agentic OS Stack — Full agent orchestration stack
• AI Image Gen Local — Local image generation pipeline
• Privacy-First AI Laptop — Air-gapped AI workstation
• OpenJarvis Intelligence Stack — Multi-agent intelligence
• OpenHands Autonomous Coder — Autonomous coding agent
• DeepSeek R1 Local Reasoning — Local reasoning models
• Hermes AI Coder Stack — Hermes-powered coding
• Aider + Ollama Vibe Coding — Vibe coding setup
• Open WebUI Full RAG — Complete RAG pipeline

Multi-Backend Container Export

Export your compiled stack to multiple deployment targets:

• Podman Compose — Rootless OCI containers via compose.yaml
• Docker Compose — Standard Docker Compose output
• LXC Containers — Per-container .conf files + lxc-launch.sh lifecycle script
• Firecracker microVMs — Per-VM vm-config.json files + firecracker-launch.sh for ultra-lightweight KVM-backed microVMs

Runtime Management

Launch and manage tools via four runtime backends, all with shell-injection-safe list-form subprocess calls and validated tool_ids / port ranges:

• systemd — Persistent system services with systemctl (5 s timeout on is-active queries)
• tmux — Session-managed terminal processes with user-scoped session names (ai_lsc_<uid>)
• desktop — One-shot CLI commands
• lxc — Full LXC container lifecycle (create, start, stop, freeze, attach) with shlex.split() argument preservation and validated container names

All child processes are tracked in a ProcessManager._launched list and reaped on application exit so the GUI does not orphan tmux windows or desktop launches.

Skills System

Extend AI-LSC with skill modules that add specialized behaviors to your tool stack. The Skills Console provides activation toggles, behavior bindings, and runtime integration.

AI Chat Console

Built-in chat interface for interacting with local LLM endpoints. Supports model selection, conversation history, and direct integration with your running stack.

DB Manager

Full-screen database management interface for inspecting and querying your stack's data stores. Hides the pipeline ticker to maximize workspace.

Verification

Validate your compiled stack configuration, check tool dependencies, and verify service connectivity before deployment.

Settings

Configure base directories, model defaults, API endpoints, logging levels, and application preferences.

Architecture

ai_lsc/
  __init__.py                 # Public API re-exports
  __main__.py                 # Entry point: python -m ai_lsc
  constants.py                # App constants, styles, 10-layer nav order
  types.py                    # Data classes: ToolMetadata, PipelineState, etc.
  guardrails.py               # Import guard for PySide6
  registry/
    __init__.py
    defaults.py                # Master registry (140 tools, full 8-key flags)
    loader.py                  # Merges per-layer files + blacklist enforcement
    manager.py                 # RegistryManager — query/filter/group tools
    validator.py               # Schema validation (8-key flags enforced)
    license_gate.py            # License compliance gating
    licenses.py                # License database
    layers/                    # 10 per-layer tool files
      host_platform.py         # L1: 9 tools
      development.py           # L2: 7 tools
      gpu.py                   # L3: 3 tools
      inference.py             # L4: 7 engines
      orchestrators.py         # L5: 26 tools
      security.py              # L6: 6 tools
      observability.py         # L7: 8 tools
      user_interfaces.py       # L8: 16 tools
      devops.py                # L9: 33 tools
      knowledge_management.py  # L10: 25 tools
    stack_templates/           # 13 pre-configured stack templates
      manager.py               # StackTemplateManager
    openengineer/              # OpenEngineer import pipeline
  runtime/
    __init__.py
    executor.py                # RuntimeExecutor — dispatch + tool_id/port validation
    installer.py               # Tool installation (URL/port/tool_id validation)
    process.py                 # ProcessManager with reap()/shutdown()
    status.py                  # Service status detection
    systemd.py                 # systemd lifecycle (no shell=True)
    tmux.py                    # tmux session mgmt (validated names, XDG sockets)
    lxc.py                     # LXC lifecycle (validated names, shlex.split)
  stack/
    __init__.py
    export.py                  # ContainerBackend — compose/LXC/Firecracker export
    connections.py             # 60-entry STACK_WIRINGS topology (ticker data source)
  ui/
    __init__.py
    protocol.py                # MainWindowProtocol (TYPE_CHECKING-typed)
    main_window.py             # AILocalStackControl — master QMainWindow + sidebar
    dialogs/
      __init__.py
      stack_wizard.py          # Legacy wizard (kept for backward compat)
      license_dialog.py        # License compliance dialog
    pages/
      infrastructure_layer_page.py  # Sidebar-integrated layer checkboxes
      ipc_stack_tab.py              # Stack Editor (templates + flow + lifecycle)
      db_manager.py                 # Full-screen DB management
      chatbot_console.py
      code_analysis_tab.py
      container_stacks_tab.py
      datasets_tab.py
      git_worktree_tab.py
      service_row.py               # Per-layer active service controls
      settings_page.py
      skills_console.py
      tools_tab.py
      verification_tab.py
    widgets/
      __init__.py
      pipeline_ticker.py          # Scrolling wiring-topology status bar
      workspace_tab.py            # Peek-style embedded web + CLI orchestration
  chat/
    __init__.py
    api.py                       # Async chat API worker (sanitized errors)
  agents/
    __init__.py
    orchestrator.py              # Multi-agent orchestration loop
    dispatcher.py                # Agent dispatch
    model_pool.py                # Model pool management
    tool_bridge.py               # Agent ↔ tool registry bridge
    skill_injector.py            # Skill injection into agent context
  skills/
    __init__.py
    resolver.py                  # SkillRuntimeResolver
  manifest/
    __init__.py
    support.py                   # Manifest generation
  utils/
    __init__.py
    filesystem.py                # Path.rglob-based walk_tree
    logging.py
    ollama.py                    # Ollama utilities
    paths.py
    process.py
  service/
    __init__.py

Installation

Prerequisites

• Python 3.11+
• PySide6 (pip install PySide6)
• Arch Linux (pacman) or equivalent package manager

Quick Install

git clone https://github.com/your-username/ai-lsc.git
cd ai-lsc
pip install -e .

Bootstrap Script

./bootstrap.sh

The bootstrap script installs all system dependencies (pacman packages), Python dependencies, and verifies your environment.

Usage

Launch the Application

python -m ai_lsc

Typical Workflow

1. Browse the Infrastructure sidebar — expand layers to discover and toggle tools (the sidebar is the wizard)
2. Select a template from the Stack Editor for a curated starting point, or build from scratch
3. Validate dependencies — AI-LSC resolves tool dependencies automatically as you toggle
4. Compile your stack — the Stack Editor validates and saves the configuration to pipeline.json
5. Watch the Pipeline Ticker — the scrolling status bar shows live wiring topology; orphans flagged red
6. Launch services — Tools start via systemd, tmux, desktop, or LXC launchers
7. Orchestrate from Workspace — every active tool gets its own sub-tab; web tools embed via QWebEngineView, CLI tools attach via tmux
8. Monitor — Active metrics dashboard shows real-time status of running tools only
9. Export — Generate Podman/Docker Compose, LXC, or Firecracker microVM configs

Security & Reliability (v3.1)

The v3.1 pass applied a comprehensive security hardening:

• No shell=True in any subprocess call across runtime/process.py, systemd.py, tmux.py, lxc.py, or installer.py (15+ sites converted to list-form argv)
• Registry blacklist enforcement — the loader strips blacklisted tool IDs (e.g., wayland compositor) at startup, preventing accidental re-introduction
• Path-traversal protection at every subprocess boundary: _validate_tool_id() rejects .., ., /, and shell metacharacters
• Port range validation on every user-supplied port (1 <= port <= 65535)
• URL scheme validation on every install_custom URL (http/https only)
• Atomic JSON writes via tempfile + fsync + os.replace with fcntl.flock advisory locking
• Hardened error messages in the chat API (no internal-detail leakage)
• Process lifecycle cleanup on application exit (ProcessManager.shutdown())
• API keys from environment — reads from env vars instead of hardcoded values
• Dynamic Qdrant embedding dimension probe (no hardcoded dimension mismatch)

Development

Project Structure

The project follows a layered architecture with clear separation of concerns:

• registry/ — Tool definitions, loader, validator, templates, blacklist
• runtime/ — Process management, launchers, installers
• stack/ — Container export backends, wiring topology
• ui/ — PySide6 interface (guarded imports, protocol-based DI, sidebar wizard)
• chat/ — Async chat API integration
• agents/ — Multi-agent orchestration, dispatch, model pool
• skills/ — Skill runtime resolver
• utils/ — Filesystem, logging, path helpers

Adding a New Tool

1. Identify the correct layer file in registry/layers/
2. Add a new entry to the TOOLS dict with the full 8-key flags schema:

'my_tool': {
    "name": "My Tool",
    "layer": "Orchestrators",
    "role": "Hands",
    "category": "Agent Framework",
    "installer": {"type": "npm", "pkg": "my-tool"},
    "launcher": {"type": "tmux", "cmd": "my-tool serve --port {port}",
                  "default_port": 8080},
    "deps": ["ollama"],
    "description": "My awesome AI tool.",
    "flags": {
        "has_cli": True,
        "has_gui": False,
        "has_web": True,
        "is_ollama": False,
        "is_docker": False,
        "is_passive": False,
        "is_mcp": False,
        "is_skills_collection": False,
    },
},

3. Run python -m ai_lsc.registry.validator to validate the schema
4. Optionally add it to a stack template in registry/stack_templates/
5. Optionally add a STACK_WIRINGS entry in stack/connections.py for Pipeline Ticker visualization

Creating a Stack Template

{
    "id": "my-template",
    "name": "My Custom Stack",
    "description": "A custom stack for my workflow",
    "version": "1.0",
    "author": "your-name",
    "tags": ["custom", "development"],
    "tools": ["ollama", "aider", "claude_code", "vllm"]
}

Save as registry/stack_templates/my-template.json.

Tech Stack

Component	Technology
UI Framework	PySide6 (Qt for Python)
Web Embedding	PySide6 QtWebEngine (servo-swap path documented)
CLI Embedding	tmux capture-pane polling at 4 Hz
Language	Python 3.11+
Package Manager	pip / uv
Container Backends	Podman, Docker, LXC, Firecracker microVMs
Service Management	systemd, tmux
IaC Tools	Terraform, Pulumi, OpenTofu, AWS CDK, Crossplane, Bicep, Terragrunt
Config Format	JSON (atomic writes via tempfile + fsync + os.replace)
Concurrency	threading.Lock for model pool, fcntl.flock for cross-process state files

License

AGPLv3

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Add tools to the appropriate layer file
4. Ensure all 10 layer files pass AST validation (python3 -c "import ast; ...")
5. Submit a pull request