# 🚀 Setup — klaude-proxy
## 🤔 ¿Qué hago? ¿Cómo lo hago? ¿Y para qué lo hago?
**¿Qué hago?**
Guía completa para desplegar klaude-proxy en Podman y conectar Claude Code al sistema de caché semántica.
**¿Cómo lo hago?**
Con Podman Compose: levanta Qdrant y el proxy en contenedores aislados con un solo comando. En macOS (M1/Apple Silicon), los contenedores corren dentro de una VM Linux ARM64 gestionada por `podman machine`.
**¿Y para qué lo hago?**
Para que cualquier instancia de Claude Code apunte al proxy en lugar de a `api.anthropic.com` directamente, añadiendo caché semántica persistente sin modificar nada más que una variable de entorno.
---
## 📋 Prerequisitos
| Herramienta | Versión mínima | Instalación |
| --- | --- | --- |
| Podman | ≥ 4.9 | `brew install podman` |
| podman-compose | ≥ 1.1 | incluido en Podman ≥ 4.9 vía `podman compose` |
| Git | cualquier | preinstalado en macOS |
| API key Anthropic | — | [console.anthropic.com](https://console.anthropic.com/) |
> 📌 **Solo necesitas una API key**: `ANTHROPIC_API_KEY`. Los embeddings corren localmente dentro del contenedor — sin APIs externas, sin coste por token de embedding.
---
## 🍎 Primera vez en macOS — inicializar Podman Machine
Podman en macOS requiere una VM Linux para ejecutar los contenedores. Solo hay que hacerlo **una vez**:
```bash
# Inicializar la VM (solo la primera vez)
podman machine init
# Arrancar la VM
podman machine start
# Verificar que está corriendo
podman machine list
```
La salida de `podman machine list` debe mostrar `RUNNING` en la columna `LAST UP`.
Para sesiones futuras, solo necesitas:
```bash
podman machine start
```
---
## ⚡ Instalación rápida
```bash
# 1. Clonar el repositorio
git clone https://github.com/Ka0s-Klaus/klaude-code-local.git
cd klaude-code-local
# 2. Crear el fichero de credenciales
cp .env.example .env
```
Edita `.env` y añade tu API key de Anthropic:
```bash
ANTHROPIC_API_KEY=sk-ant-api03-...
```
Solo esta línea es necesaria. El resto de variables tienen defaults seguros.
```bash
# 3. Levantar el stack (Qdrant + proxy)
./scripts/setup.sh
```
El primer arranque descarga e instala el modelo de embeddings (`nomic-embed-text-v1.5`, ~270 MB) dentro de la imagen Docker. Tarda varios minutos. Los arranques posteriores son inmediatos gracias a la capa cacheada.
Al terminar verás:
```text
✅ Stack running:
CONTAINER ID IMAGE ... STATUS
... localhost/klaude-proxy:... ... Up
... qdrant/qdrant:v1.12.1 ... Up
📡 Proxy listening on http://0.0.0.0:8080
🗄️ Qdrant dashboard at http://localhost:6333/dashboard
👉 Configure Claude Code:
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=<your-anthropic-key>
```
---
## 🔌 Conectar Claude Code al proxy
Añade esta línea a tu `~/.zshrc` para que persista entre sesiones de terminal:
```bash
echo 'export ANTHROPIC_BASE_URL=http://localhost:8080' >> ~/.zshrc
source ~/.zshrc
```
`ANTHROPIC_API_KEY` ya debe estar en tu entorno (si no, añádela también al `~/.zshrc`).
A partir de ahora, cualquier sesión de Claude Code pasará por el proxy automáticamente.
---
## ✅ Verificar que todo funciona
```bash
# 1. El proxy responde
curl http://localhost:8080/health
# → {"status":"ok","version":"0.1.0"}
# 2. Qdrant está operativo
curl http://localhost:8080/cache/stats
# → {"collection":"klaude_cache","vectors_count":0,"points_count":0,"status":"green"}
# 3. Lanzar Claude Code — debe arrancar sin errores
claude
```
En los logs del proxy verás el flujo en tiempo real:
```bash
podman logs -f klaus-proxy
```
- Primera pregunta → `CACHE MISS` — se reenvía a Anthropic y se almacena en Qdrant
- Misma pregunta (o similar) → `CACHE HIT` — respuesta desde Qdrant sin llamar a Anthropic
---
## 📊 Monitorizar el cache
```bash
# Estadísticas resumidas
./scripts/stats.sh
# Logs del proxy en tiempo real
podman logs -f klaus-proxy
# Dashboard de Qdrant (interfaz web)
open http://localhost:6333/dashboard
# Logs de Qdrant
podman logs -f klaus-qdrant
```
---
## 🔄 Uso diario
```bash
# Arrancar (después de reiniciar el Mac o parar el stack)
podman machine start # si la VM no está corriendo
./scripts/setup.sh # levanta Qdrant + proxy
# Parar el stack (conserva los vectores cacheados)
./scripts/teardown.sh
# Ver estado del stack
podman compose -f podman/compose.yaml ps
```
---
## 🌐 Acceso desde otras máquinas (LAN / VPN)
Si quieres que otras instancias de Claude Code en la red usen la misma caché:
**En el host que ejecuta Podman**, abre el puerto en el firewall:
```bash
# macOS — permitir el puerto 8080 (si tienes firewall activo)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which podman)
```
**En cada cliente remoto**, apunta al host que corre el proxy:
```bash
export ANTHROPIC_BASE_URL=http://<IP-del-host-proxy>:8080
export ANTHROPIC_API_KEY=<tu-anthropic-api-key>
```
---
## ↩️ Desconectar el proxy (volver a Anthropic directo)
```bash
unset ANTHROPIC_BASE_URL
```
Para eliminar definitivamente la variable del entorno, bórrala de tu `~/.zshrc`.
---
## 🛑 Parar y limpiar el stack
```bash
./scripts/teardown.sh
# El script pregunta si eliminar el volumen (y los vectores cacheados)
```
---
## 🔗 Documentos relacionados
- [architecture.md](architecture.md) — Cómo funciona internamente
- [proxy.md](proxy.md) — Referencia de API y variables de entorno
- [cache.md](cache.md) — Estrategia de caché y ajuste del umbral