---
project:
  name: Repository README
  status: active
  category: documentation
  source: live-verification
  created: 2026-01-06
  updated: 2026-04-19
  description: Main repository overview and vault usage guide
  tags: [documentation, setup, obsidian]
---

# homelabagentroot

Unified GitOps repository for managing a multi-node homelab cluster.

## Structure

```
homelabagentroot/
├── homelab/          # Infrastructure configs (per-host docker-compose, traefik, etc.)
│   ├── ubuntu/       # Primary Docker host (59 containers)
│   ├── grizzley/     # Edge ingress (Traefik, Komodo, Hermes)
│   ├── ice/          # Control plane (OpenCode, App Factory)
│   ├── proxmox/      # Hypervisor configs
│   └── truenas/      # Storage configs
├── scripts/          # Automation and management scripts
│   ├── authentik/    # SSO/OIDC configuration scripts
│   ├── homelab/      # Deployment, inventory, drift detection
│   └── maintenance/  # Backup and repair
├── ansible/          # Orchestration playbooks
├── obsidian-vault/   # Documentation vault (this directory)
├── .opencode/        # OpenCode agent config, skills, commands
└── reference/        # External codebase references (read-only)
```

## GitOps Commands

```bash
make sync-pull       # Pull runtime configs from hosts
make save-runtime    # Pull + commit + push
make sync-push       # Push vaulted configs to hosts
make deploy-all      # Restart services on all hosts
make validate        # Validate all docker-compose files
```

## Related

- [[homelab/project.md|Homelab Infrastructure]]
- [[ai-assistant/project.md|AI Assistant]]
- [[automation/project.md|Automation Scripts]]
- [[platform-config/project.md|Platform Configuration]]