System Requirements

Complete hardware and software prerequisites for running the LLM Platform and OSSA-compliant agents.

Hardware Requirements

Minimum Specifications

Development Environment: - CPU: 4 cores (x86_64 or ARM64) - RAM: 8 GB minimum - Storage: 20 GB free space (SSD recommended) - Network: Broadband internet connection

Production Environment: - CPU: 8+ cores recommended (x86_64 or ARM64) - RAM: 16 GB minimum, 32 GB recommended - Storage: 100 GB+ free space (SSD required) - Network: High-bandwidth, low-latency connection

Recommended Specifications

Optimal Development Setup: - CPU: 8+ cores (Apple Silicon M1/M2/M3 or Intel i7/i9) - RAM: 16 GB minimum, 32 GB optimal - Storage: 256 GB+ NVMe SSD - GPU: Optional, beneficial for local ML model inference

Production Kubernetes Cluster: - Nodes: 3+ worker nodes minimum - CPU per Node: 8+ cores - RAM per Node: 32 GB minimum - Storage: Persistent volumes with 500 GB+ capacity - Network: 10 Gbps inter-node connectivity

Software Requirements

Operating Systems

Supported Platforms: - ✅ macOS 12+ (Monterey, Ventura, Sonoma) - Recommended for development - ✅ Linux - Ubuntu 22.04+, Debian 11+, RHEL 8+, Fedora 36+ - ✅ Windows 10/11 with WSL2 (Ubuntu 22.04+ in WSL)

Container Runtimes: - Docker Desktop 4.x+ (macOS/Windows) - OrbStack 1.x+ (macOS alternative - optimized performance) - Docker Engine 24.x+ (Linux) - Podman 4.x+ (alternative to Docker)

Core Dependencies

Required Software

PHP Platform: - PHP: 8.3+ (Required for Drupal 11) - Extensions: gd, mbstring, xml, curl, zip, pdo_mysql, pdo_pgsql, opcache - Install: brew install php@8.3 (macOS) or apt install php8.3 (Ubuntu)

Node.js Ecosystem: - Node.js: 20.x LTS or 22.x (Required for BuildKit CLI) - Install: nvm install 20 or download from nodejs.org - npm: 10.x+ (bundled with Node.js) - pnpm: 8.x+ (optional, faster alternative)

Package Managers: - Composer: 2.6+ (PHP dependency manager) - Install: brew install composer or getcomposer.org

Version Control: - Git: 2.40+ - Install: brew install git or apt install git

Container Orchestration: - Docker: 24.x+ or OrbStack 1.x+ - Install: docker.com or orbstack.dev - DDEV: 1.22+ (recommended for Drupal development) - Install: brew install ddev/ddev/ddev

Optional but Recommended

Database Clients: - PostgreSQL Client: 15+ (psql CLI) - MySQL Client: 8.0+ (mysql CLI) - Redis CLI: 7.0+ (redis-cli)

Kubernetes Tools: - kubectl: 1.28+ (Kubernetes CLI) - Helm: 3.13+ (Package manager for Kubernetes) - k9s: Latest (Terminal UI for Kubernetes - highly recommended)

Monitoring & Debugging: - jq: Latest (JSON processor) - curl: 8.x+ (HTTP client) - watch: Latest (command monitoring)

Platform-Specific Components

LLM Platform (Drupal)

Database: - PostgreSQL: 15+ (recommended) or MySQL 8.0+ - Drupal supports both, PostgreSQL preferred for production

Web Server (for non-DDEV setups): - Apache: 2.4+ with mod_rewrite enabled, or - Nginx: 1.24+ with PHP-FPM

Caching: - Redis: 7.0+ (recommended for Drupal cache) - Memcached: 1.6+ (alternative)

BuildKit & OSSA Agents

AI Gateway: - LLM Gateway: Bundled with platform (Node.js service) - Port: 4000 (default) - Auto-installed via LLMCLI

Vector Database: - Qdrant: 1.7+ (vector similarity search) - Port: 6333 (default) - Auto-installed via LLMCLI

Message Queue (Production): - Apache Kafka: 3.6+ (for agent orchestration) - Managed via Docker Compose or Kubernetes

Observability Stack (Production): - Prometheus: 2.48+ (metrics) - Grafana: 10.2+ (visualization) - Jaeger: 1.52+ (distributed tracing) - Loki: 2.9+ (log aggregation)

Development Tools

Integrated Development Environments

Recommended IDEs: - VS Code: Latest with extensions: - PHP Intelephense - ESLint - Prettier - YAML - Docker - PHPStorm: 2024.1+ (JetBrains - premium option) - Cursor: Latest (AI-enhanced VS Code fork) - Zed: Latest (high-performance editor)

CLI Tools for Productivity

Essential: - buildkit: Install globally via npm (npm install -g @bluefly/agent-buildkit) - ossa: Install globally via npm (npm install -g @bluefly/openstandardagents) - llmcli: Install globally via npm (npm install -g @bluefly/llmcli) - drush: 12.x+ (Drupal CLI - installed via Composer)

Recommended: - gh: GitHub CLI (for GitHub operations) - glab: GitLab CLI (for GitLab operations) - httpie: Modern HTTP client (http command) - bat: Better cat with syntax highlighting - fzf: Fuzzy finder for command history

Network Requirements

Ports

Development (Local): - 3000: BuildKit API server - 4000: LLM Gateway API - 5432: PostgreSQL - 6333: Qdrant vector database - 6379: Redis - 8080: Drupal (via DDEV) - 8443: Drupal HTTPS (via DDEV) - 9090: Prometheus - 3001: Grafana

Production (Kubernetes): - 80: HTTP ingress - 443: HTTPS ingress - 6443: Kubernetes API server - Internal cluster networking for services

External Services

Required API Access: - GitLab: gitlab.com or self-hosted GitLab instance - API access for issue tracking, MR management - OAuth authentication - NPM Registry: registry.npmjs.com or GitLab Package Registry - For installing BuildKit CLI and dependencies

Optional AI Provider APIs: - OpenAI: api.openai.com (GPT models) - Anthropic: api.anthropic.com (Claude models) - HuggingFace: huggingface.co (open models) - Apple Intelligence: Apple Foundation Models (macOS only)

Security Requirements

Authentication

GitLab Integration: - Personal Access Token with scopes: api, read_api, read_registry, write_registry - OAuth client credentials for agent authentication

API Tokens: - Store tokens securely in ~/.tokens/ directory - Never commit tokens to version control - Use environment variables for production

SSL/TLS

Development: - DDEV provides automatic self-signed certificates - Trust DDEV CA: mkcert -install

Production: - Valid SSL certificates from Let's Encrypt or commercial CA - TLS 1.2+ required - Certificate management via cert-manager (Kubernetes)

Performance Considerations

Local Development

Disk I/O: - Use SSD for Docker volumes and source code - Enable OrbStack VirtIO-FS for 10x faster file mounting (macOS) - Avoid Docker Desktop NFS mounts on macOS

Memory Management: - Allocate 8 GB+ RAM to Docker Desktop - Enable swap space for large composer operations - Use ddev stop when not actively developing

Production Deployment

Resource Allocation: - Agent pods: 512 MB - 2 GB RAM each - Database pods: 4 GB+ RAM - Vector database: 8 GB+ RAM for production workloads - Reserve 20% cluster capacity for auto-scaling

Storage: - Use SSD-backed persistent volumes (PVs) - Enable volume snapshots for backups - Configure storage class with high IOPS (5000+)

Verification Checklist

Before proceeding to installation, verify you have:

[ ] Operating system: macOS 12+, Linux (Ubuntu 22.04+), or Windows 10+ with WSL2
[ ] PHP 8.3+ with required extensions installed
[ ] Node.js 20.x+ installed
[ ] Composer 2.6+ installed
[ ] Git 2.40+ installed
[ ] Docker 24.x+ or OrbStack 1.x+ installed
[ ] DDEV 1.22+ installed (for Drupal development)
[ ] Minimum 8 GB RAM available
[ ] Minimum 20 GB free disk space (SSD)
[ ] Stable internet connection for downloading dependencies
[ ] GitLab account with API access token
[ ] Ports 3000, 4000, 5432, 6333, 8080 available

Platform-Specific Notes

macOS

Recommended Setup: - Use OrbStack instead of Docker Desktop for 10x better performance - Install Xcode Command Line Tools: xcode-select --install - Use Homebrew for package management: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Performance:

# Install OrbStack (faster than Docker Desktop)
brew install orbstack

# Increase file watchers for large projects
echo "kern.maxfiles=65536" | sudo tee -a /etc/sysctl.conf
echo "kern.maxfilesperproc=65536" | sudo tee -a /etc/sysctl.conf

Linux

Package Installation (Ubuntu/Debian):

# Update package index
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y php8.3 php8.3-{cli,fpm,gd,mbstring,xml,curl,zip,mysql,pgsql,opcache} \
  composer git curl wget unzip postgresql-client redis-tools

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Windows (WSL2)

Setup WSL2:

# In PowerShell (Administrator)
wsl --install -d Ubuntu-22.04
wsl --set-default-version 2

# Restart Windows, then in WSL2 terminal:
# Follow Linux installation instructions above

Integration: - Install Docker Desktop with WSL2 backend enabled - Access Windows files via /mnt/c/ - Use VS Code with Remote-WSL extension

Next Steps

Once all requirements are verified:

Proceed to Development Setup for local environment configuration
Or jump to Production Deployment for Kubernetes setup
Review Your First Agent to understand OSSA workflow

Troubleshooting

Common Issues

Docker permission denied:

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

PHP extensions missing:

# macOS
brew install php@8.3
brew link php@8.3

# Ubuntu/Debian
sudo apt install php8.3-{gd,mbstring,xml,curl,zip,mysql,pgsql,opcache}

Node.js version mismatch:

# Install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Install and use Node 20
nvm install 20
nvm use 20
nvm alias default 20

Port conflicts:

# Check what's using a port (macOS/Linux)
lsof -i :8080

# Kill process using port
kill -9 $(lsof -t -i:8080)

For additional help, see Common Pitfalls or consult the LLM Platform Documentation.