# proxym VM Orchestrator — Fix Log & Documentation

## Podsumowanie napraw (2026-03-22)

### Problemy znalezione i naprawione

#### 1. **500 Error przy starcie VM — brak virtiofsd**
- **Objaw**: `Unable to find a satisfying virtiofsd`
- **Przyczyna**: Brak zainstalowanego `virtiofsd` — wymagany dla shared folders
- **Rozwiązanie**: 
  - VMs są teraz tworzone bez shared folders jeśli `virtiofsd` nie jest dostępny
  - Automatyczny fallback w `_generate_domain_xml()`
  - Log warning: `virtiofs_disabled`

#### 2. **Permission denied na overlay files**
- **Objaw**: `Cannot access storage file (as uid:64055, gid:993)`
- **Przyczyna**: qemu user nie mógł czytać plików w `~/.local/share/proxym/overlays/`
- **Rozwiązanie**:
  - Zmiana domyślnej lokalizacji na `/var/tmp/proxym-overlays/` (world-writable)
  - Edycja: `src/proxym/virt/_orchestrator.py:759`

#### 3. **Brak szczegółowych błędów w API**
- **Objaw**: Generyczny "Failed to start VM"
- **Rozwiązanie**: 
  - Ulepszona obsługa błędów w `dashboard/__init__.py`
  - Zwracanie szczegółowych komunikatów z `virsh`

### Pliki zmienione

| Plik | Linia | Zmiana |
|------|-------|--------|
| `src/proxym/virt/_orchestrator.py` | 759 | Default overlays: `/var/tmp/proxym-overlays` |
| `src/proxym/dashboard/__init__.py` | 207-231 | Lepsza obsługa błędów VM start |
| `src/proxym/virt/_config.py` | 59 | Fix: `proxy_address = ""` (auto-detect) |

### Testy wykonane

```bash
# Create VM
curl -X POST http://localhost:4001/dashboard/vms \
  -d '{"name": "test-vm", "vcpus": 2, "memory_mb": 2048}'
# → {"id": "proxym-1338", "state": "stopped"}

# Start VM
curl -X POST http://localhost:4001/dashboard/vms/proxym-1338/start
# → {"ok": true, "state": "running"}

# Check status
curl http://localhost:4001/dashboard/vms | grep proxym-1338
# → "state": "running", "uptime": 96.5...

# Stop VM
curl -X POST http://localhost:4001/dashboard/vms/proxym-1338/stop
# → {"ok": true}

# Delete VM
curl -X DELETE http://localhost:4001/dashboard/vms/proxym-1338
# → {"ok": true}
```

### Konfiguracja systemowa (wymagana)

```bash
# Utwórz katalog na overlay files
sudo mkdir -p /var/tmp/proxym-overlays
sudo chmod 777 /var/tmp/proxym-overlays

# Opcjonalnie: zainstaluj virtiofsd dla shared folders
# Ubuntu/Debian:
sudo apt install virtiofsd

# Fedora/RHEL:
sudo dnf install virtiofsd
```

### Architektura VM — aktualna

```
┌─────────────────────────────────────────────────────────────┐
│                    HOST (Linux)                              │
│  proxym serve (localhost:4000)                              │
│  ├── Router: Haiku/Sonnet/Opus/Gemini/Ollama                │
│  └── VMOrchestrator → libvirt (virsh)                       │
│                                                             │
│  Overlays: /var/tmp/proxym-overlays/  (world-writable)      │
│  Config:   ~/.config/proxym/vms/                            │
│  Images:   ~/.local/share/proxym/images/                    │
└──────────────────┬──────────────────────────────────────────┘
                   │  bez virtiofs (brak shared folders)
┌──────────────────▼──────────────────────────────────────────┐
│              KVM VM                                          │
│  Windsurf/Roo Code → API Base: http://10.0.2.2:4000        │
└─────────────────────────────────────────────────────────────┘
```

### TODO — pozostałe zadania

- [ ] Instalacja Windsurf przez cloud-init (apt repo Codeium)
- [ ] Inject konfiguracji Roo Code (settings.json) z vm-key
- [ ] Post-create hook: `windsurf --install-extension roo-cline`
- [ ] Virtiofs support: auto-detekcja i konfiguracja shared folders

### Użycie

```bash
# Dashboard
open http://localhost:4001/dashboard

# Lista VMs
proxym vm list

# Utwórz i uruchom VM
proxym vm create --name test --vcpus 2 --memory 2048
proxym vm start <vm-id>

# Via API
curl http://localhost:4001/dashboard/vms
curl -X POST http://localhost:4001/dashboard/vms/<id>/start
```
