5.4 KiB

Raw Permalink Blame History

Quickstart Guide

Get AI Local Stack Control up and running in under 5 minutes.

Prerequisites

Requirement	Minimum	Recommended
OS	Arch Linux	Arch Linux / EndeavourOS
Python	3.11	3.12+
RAM	8 GB	16 GB+ (for LLM inference)
Disk	4 GB free	20 GB+ (for model storage)
GPU	None	NVIDIA (CUDA) or AMD (ROCm)

Installation

Option 1: Bootstrap Script (Recommended)

# Clone the repository
git clone https://github.com/your-username/ai-lsc.git
cd ai-lsc

# Run the bootstrap script (installs system + Python deps)
chmod +x bootstrap.sh
./bootstrap.sh

# Launch the application
python -m ai_lsc

Option 2: Manual Install

Step 1: System Dependencies

# Core packages (Arch Linux)
sudo pacman -S python python-pip python-pyqt6 pyside6 \
    git tmux ripgrep fd tree-sitter sqlite redis

# Optional: GPU support
sudo pacman -S cuda        # NVIDIA
# sudo pacman -S rocm-hip-sdk  # AMD

# Optional: Container runtimes
sudo pacman -S podman docker
# Optional: LXC support
sudo pacman -S lxc lxcfs

Step 2: Python Dependencies

cd ai-lsc

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate

# Install PySide6 and dependencies
pip install PySide6
pip install -e .

Step 3: Verify Installation

# Check that the registry loads correctly
python -c "
from ai_lsc import DEFAULT_REGISTRY, validate_registry
errors = validate_registry(DEFAULT_REGISTRY)
print(f'Registry loaded: {len(DEFAULT_REGISTRY)} tools')
print(f'Validation errors: {len(errors)}')
"

# Expected output:
# Registry loaded: 115 tools
# Validation errors: 0

Step 4: Launch

python -m ai_lsc

First Launch

When you launch AI-LSC for the first time, you will see the Stack Template Wizard. This is your entry point for configuring your AI stack.

Choosing a Template

Template	Best For	Tool Count
Claude Code Setup	Claude Code development workflow	11
Free Claude Code	Minimal Claude Code environment	4
Local LLM Lab	Self-hosted LLM experimentation	10
SaaS Integrations	Production deployment with SSL/CDN	12

Manual Configuration

If you prefer to build your stack from scratch:

Select Create From Scratch in the wizard
Navigate to the Infrastructure section in the sidebar
Expand each layer and toggle tools on/off
Use the IPC Stack tab to validate dependencies
Click Compile to save your stack configuration

Post-Setup

Installing a Base LLM

Most tools depend on Ollama as the local LLM runtime:

# Install Ollama (if not already installed)
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3
ollama pull codellama    # Good for coding assistance
ollama pull mistral      # Lightweight general-purpose

Starting Services

After configuring your stack in the IPC Stack tab:

Click Compile to save the stack configuration
Switch to the Monitor tab
Click Start All or start individual services
Check service status indicators (green = running)

Connecting the Chat Console

Once Ollama is running:

Navigate to the Chat section
Select a model from the dropdown (e.g., llama3, codellama)
Start chatting with your local AI assistant

Common Tasks

Adding a New Tool

Identify the target layer in registry/layers/
Add the tool entry following the canonical schema
Restart the application — the tool appears automatically

Exporting to Containers

Open Deployment Targets from the sidebar
Select your backend: Podman, Docker, or LXC
Click Export to generate configuration files
Deploy with podman compose up or lxc-launch.sh

Managing LXC Containers

# Create a container from exported config
sudo lxc-create -n ollama -f ollama.conf

# Start the container
sudo lxc-start -n ollama

# Attach to the container console
sudo lxc-attach -n ollama

# Freeze/unfreeze
sudo lxc-freeze -n ollama
sudo lxc-unfreeze -n ollama

# Destroy
sudo lxc-stop -n ollama
sudo lxc-destroy -n ollama

Troubleshooting

PySide6 Import Error

ModuleNotFoundError: No module named 'PySide6'

Fix: Install PySide6: pip install PySide6

Registry Loading Errors

ERROR: Failed to load layer file: SyntaxError

Fix: Validate layer files:

python3 -c "
import ast, os
for f in os.listdir('ai_lsc/registry/layers'):
    if f.endswith('.py') and f != '__init__.py':
        ast.parse(open(f'ai_lsc/registry/layers/{f}').read())
        print(f'{f}: OK')
"

Service Won't Start

Check the Monitor tab for error messages
Verify the tool is installed: which <tool_name>
Check launcher command in the registry entry
For systemd services: systemctl --user status <service>

Ollama Connection Refused

Ensure Ollama is running: ollama serve or systemctl --user start ollama
Check port: curl http://localhost:11434/api/tags
Verify the endpoint in Settings matches your Ollama port

Next Steps

Explore the Infrastructure section to understand the 13-layer architecture
Try different Stack Templates to find the right combination for your workflow
Set up the Skills Console to extend your tool capabilities
Use Code Analysis to inspect and understand your project dependencies

5.4 KiB Raw Permalink Blame History