# Particle-OS VM Management Setup

This guide helps you set up remote VM management for your headless Particle-OS development server.

## Quick Start

1. **Test the connection:**
   ```bash
   just -f vm-justfile test-connection
   ```

2. **List existing VMs:**
   ```bash
   just -f vm-justfile list
   ```

3. **Create a test VM:**
   ```bash
   just -f vm-justfile create particle-test 20G
   ```

## Configuration

The system uses these environment variables (set in `.vm-config`):

- `VM_SERVER`: Your headless server (e.g., `joe@192.168.122.76`)
- `VM_DIR`: VM storage directory (`/var/lib/libvirt/images`)
- `ISO_DIR`: ISO storage directory (`/var/lib/libvirt/isos`)
- `VM_SSH_KEY`: SSH key path (optional)
- `VM_SSH_PORT`: SSH port (default: 22)

## Setting Up Environment Variables

### Option 1: Export in your shell
```bash
export VM_SERVER=joe@192.168.122.76
export VM_DIR=/var/lib/libvirt/images
export ISO_DIR=/var/lib/libvirt/isos
```

### Option 2: Use .env file
```bash
# Copy .vm-config to .env
cp .vm-config .env
# Then source it
source .env
```

## Connecting from virt-manager

On your other PC with virt-manager:

1. **Add Connection:**
   - File → Add Connection
   - Hypervisor: QEMU/KVM
   - Connection: `qemu+ssh://joe@192.168.122.76/system`

2. **VNC Access:**
   - VMs will be accessible via VNC on port 5900
   - Connect to: `192.168.122.76:5900`

## Common Commands

```bash
# VM Management
just -f vm-justfile create <name> <size> [iso] [ram] [vcpus]
just -f vm-justfile start <name>
just -f vm-justfile stop <name>
just -f vm-justfile status <name>
just -f vm-justfile remove <name>

# Monitoring
just -f vm-justfile info <name>
just -f vm-justfile console <name>
just -f vm-justfile get-ip <name>

# Storage
just -f vm-justfile storage-pool-list
just -f vm-justfile list-storage-files
just -f vm-justfile list-isos
```

## Troubleshooting

### Connection Issues
- Check SSH access: `ssh joe@192.168.122.76`
- Verify libvirt is running: `virsh version --short`
- Check firewall settings

### VM Creation Issues
- Ensure sufficient disk space
- Check libvirt permissions
- Verify network configuration

### VNC Issues
- Check if port 5900 is open
- Verify VNC is enabled in VM config
- Try different VNC viewer

## Security Notes

- VNC is unencrypted - use SSH tunnel for production
- Consider setting up SSH key authentication
- Restrict network access to VNC port
- Use firewall rules to limit access

## Next Steps

1. Test basic connectivity
2. Create a simple test VM
3. Connect via virt-manager
4. Test VNC access
5. Create Particle-OS test VMs