# Documentation for Kamiwaza 0.12.0

Version: 0.12.0

## Hardware Requirements

### CPU
- **Minimum Cores**: 8+ cores
- **Recommended Cores**: 16+ cores for CPU-based inference workloads
- **Architecture**:
  - Linux: x64/amd64 (64-bit)
  - Windows: x64 (64-bit)
  - macOS: ARM64 (Apple Silicon) only

### Memory
#### System RAM

| Mode          | Minimum | Recommended | Notes                                                      |
|---------------|---------|-------------|------------------------------------------------------------|
| **Lite Mode** | 16GB    | 32GB       | SQLite database; limited capacity for apps/tools           |
| **Full Mode** | 32GB    | 64GB+      | CockroachDB + DataHub; production workloads                |
| **GPU Workloads** | 32GB | 64GB+      | System RAM alongside GPU vRAM                               |

#### GPU Memory (vRAM)
- **GPU Inference**: 16GB+ vRAM required
- **Recommended**: 32GB+ vRAM for optimal GPU inference performance

### GPU (Optional)
Kamiwaza supports multiple GPU and accelerator platforms:

**Discrete GPUs:**
- NVIDIA GPUs with compute capability 7.0+ (Linux)
- NVIDIA RTX / Intel Arc (Windows via WSL)

**Unified Memory Systems:**
- **NVIDIA DGX Spark** - GB10 Grace Blackwell, 128GB unified memory
- **AMD Ryzen AI Max+ 395** - "Strix Halo" platform, up to 128GB unified memory
- **Apple Silicon M-series** - Unified memory architecture (macOS only)

### Storage
Storage requirements are the same across all platforms.

#### Storage Performance
- **Required**: SSD (Solid State Drive)
- **Preferred**: NVMe SSD for optimal performance
- **Minimum**: SATA SSD
- **Note**: Model weights can be on a separate HDD but load times will increase significantly

#### Storage Capacity
- **Minimum**: 100GB free disk space
- **Recommended**: 200GB+ free disk space
- **Enterprise Edition**: Additional space for /opt/kamiwaza persistence

#### Capacity Planning

| Component           | Minimum | Recommended | Notes                                            |
|---------------------|---------|-------------|--------------------------------------------------|
| **Operating System**| 20GB    | 50GB       | Ubuntu/RHEL base + dependencies                  |
| **Kamiwaza Platform**| 50GB   | 50GB       | Python environment, Ray, services                |
| **Model Storage**   | 50GB    | 500GB+     | Depends on number and size of models             |
| **Database**        | 10GB    | 50GB       | CockroachDB for metadata                         |
| **Vector Database** | 10GB    | 100GB+     | For embeddings (if enabled)                      |
| **Logs & Metrics**  | 10GB    | 50GB       | Rotated logs, Ray dashboard data                  |
| **Scratch Space**   | 20GB    | 100GB      | Temporary files, downloads, builds                |
| **Total**           | **170GB** | **900GB+** |                                                  |

#### Storage Performance Requirements
**Local Storage (Single Node):**
- **Minimum:** SATA SSD (500 MB/s sequential read)
- **Recommended:** NVMe SSD (2000+ MB/s sequential read)

**Performance Targets:**
- **Sequential Read:** 2000+ MB/s (model loading)
- **Sequential Write:** 1000+ MB/s (model downloads, checkpoints)
- **4K Random Read IOPS:** 50,000+ (database, concurrent access)
- **4K Random Write IOPS:** 20,000+ (database writes, logs)

## Supported Operating Systems
### Linux
- **Ubuntu**: 24.04 and 22.04 LTS via .deb package installation (x64/amd64 architecture only)
- **Red Hat Enterprise Linux (RHEL)**: 9

### Windows
- **Windows 11** (x64 architecture) via WSL with MSI installer

### macOS
- **macOS 15.0 (Sequoia) or later**, Apple Silicon (ARM64) only

## Software Dependencies
### Pre-requisites (User Must Install)
Before running the Kamiwaza installer, ensure the following are installed:

| Component | Requirement | Installation Guide |  
|-----------|-------------|--------------------|  
| **Docker** | Docker Engine 24.0+ with Compose 2.23+ | [Docker Install Guide](https://docs.docker.com/engine/install/) |  
| **Browser** | Chrome 141+ (tested and recommended) | [Download Chrome](https://www.google.com/chrome/) |

### Verifying System Requirements
Use these commands to verify your system meets the requirements before installation.
### Docker
```bash
docker --version
```
### Python
```bash
python3 --version
```

### System Resources
```bash
free -h
```

## Hardware Recommendation Tiers
Kamiwaza is a distributed AI platform built on Ray that supports both CPU-only and GPU-accelerated inference.
### GPU Memory Requirements by Model Size

| Model Example                | Parameters | Minimum vRAM | Notes                                              |
|------------------------------|------------|--------------|----------------------------------------------------|
| **GPT-OSS 20B**             | 20B        | 24GB         | Fits 1x 24GB GPU (e.g., L4/RTX 4090)               |
| **GPT-OSS 120B**            | 120B       | 80GB         | 1x H100/H200 or 2x A100 80GB recommended           |
| **Qwen 3 235B A22B**        | 235B       | 150GB        | 2x H200 (282GB) or 2x B200 (384GB) ideal          |
| **Qwen 3-VL 235B A22B**     | 235B       | 150GB        | Budget +20-30% vRAM for high-res vision inputs     |

### Tier 1: Development & Small Models
**Use Case:** Local development, testing, small to medium model deployment (up to 13B parameters)
### Tier 2: Production - Medium to Large Models
**Use Case:** Production deployment of medium to large models (13B-70B parameters), high throughput
### Tier 3: Enterprise Multi-Node Cluster
**Use Case:** Enterprise deployment with multiple models, high availability, horizontal scaling, 99.9%+ SLA

## Network Configuration
### Network Bandwidth Requirements
#### Single Node Deployment
- **Minimum:** 1 Gbps (for model downloads, API traffic)
- **Recommended:** 10 Gbps (for high-throughput inference)
#### Multi-Node Cluster
- **Minimum:** 10 Gbps Ethernet
- **Recommended:** 25-40 Gbps Ethernet or InfiniBand

### Required Kernel Modules (Enterprise Edition Linux Only)
- overlay
- br_netfilter

### Community Edition Networking
- Uses standard Docker bridge networks
  
## Directory Structure
### Enterprise Edition
Note: This is created by the installer and present in cloud marketplace images.
```text
/etc/kamiwaza/
├── config/
├── ssl/      # Cluster certificates
└── swarm/    # Swarm tokens
/opt/kamiwaza/
├── containers/  # Docker root (configurable)
├── logs/
├── nvm/        # Node Version Manager
└── runtime/    # Runtime files
```

### Community Edition
We recommend `${HOME}/kamiwaza` or something similar for `KAMIWAZA_ROOT`.
```text
$KAMIWAZA_ROOT/
├── env.sh
├── runtime/
└── logs/
```

## Important Notes
- **System Impact**: Network and kernel configurations can affect other services
- **Security**: Certificate generation and management for cluster communications
- **Storage**: Enterprise Edition requires specific storage configuration
- **Network**: Enterprise Edition requires specific network ports for cluster communication
- **Docker**: Custom Docker root configuration may affect other containers
  
**Further documentation can be accessed for specific details on each aspect discussed above.**