🐍 Qué instalar en la máquina
El HealthOS es deliberadamente simple: los scripts son Python puro (stdlib) — solo el advice.py pide pip install requests. Antes de crear cualquier cuenta, deja cuatro herramientas básicas listas en la máquina. Las instalas una vez y sigues con el resto.
🟢 ¿Nuevo por aquí? Dos términos antes de continuar
- CLI — «interfaz de línea de comandos»: un programa que ejecutas escribiendo en la terminal, sin una ventana gráfica. El Supabase CLI es lo que envía la base de datos a la nube mediante un comando.
- Runtime — el "motor" que ejecuta un tipo de código. Python ejecuta los scripts; Node ejecuta el agente y el servidor del dashboard.
📊 Cómo leer: las cuatro herramientas básicas (cian, a la izquierda) solo necesitan existir una vez. Python y Node son obligatorios; ffmpeg solo hace falta si vas a generar clips de entrenamiento; Supabase CLI envía la base de datos en la Ruta 2.2.
| Herramienta | ¿Obligatoria? | Para qué |
|---|---|---|
| Python 3.9+ | Sí | Ejecuta los scripts (stdlib). Solo advice.py usa pip install requests. |
| Node | Sí | Ejecuta el agente y el servidor del dashboard. |
| ffmpeg | Opcional | Solo para exercise_clip.py (clips de demostración de entrenamiento). |
| Supabase CLI | Sí | Aplica las migrations (crea las 14 tablas); se usó en la 2.2. |
python3 --version && node --versionPython 3.11.6 e v20.11.0. Si Python aparece por debajo de la versión 3.9 o muestra "command not found", instálalo o actualízalo antes de continuar. (ffmpeg y Supabase CLI: comprueba con ffmpeg -version e supabase --version — el primero solo si vas a usar clips.)Conceptos clave
Los scripts no dependen de paquetes externos (casi no hay nada que instalar).
Los dos motores obligatorios: scripts y agente.
Solo para clips de entrenamiento.
Impulsa la base de datos; protagonista de la 2.2.
☁️ Crear el proyecto privado de Supabase
O Supabase es donde se almacenarán TODOS tus datos de salud —comida, entrenamiento, peso, análisis, signos vitales, metas y la memoria de los mensajes. Por eso tiene que estar privado, en tu cuenta. Aquí solo creas el proyecto y guardas cuatro secretos; crear las tablas es el paso 2.2.
🟢 ¿Nuevo por aquí?
Supabase es una base de datos PostgreSQL en la nube + almacenamiento de archivos, con un panel web. Piensa en él como el «disco duro del coach»: todo lo que registras se convierte en una fila ahí, y el agente consulta esos datos en cada conversación.
Crea la cuenta y un proyecto nuevo
En supabase.com, «New project». El plan gratuito es suficiente para una persona.
Elige una región adecuada
Prefiere la región más cercana a ti (menos latencia). Para Brasil, normalmente South America (São Paulo).
Define y guarda la contraseña de la base de datos
La contraseña de la base de datos se convierte en el SUPABASE_DB_PASSWORD — Supabase CLI la necesitará en la 2.2 para enviar las migrations.
Copia la URL y las claves (Settings → API)
Obtén el SUPABASE_URL, a SUPABASE_ANON_KEY (pública) y la SUPABASE_SERVICE_ROLE_KEY (servidor). Guárdalo para el tema 6.
🔒 Anon × Service-role — dos claves, dos mundos
A anon es pública; con la RLS activada y sin políticas (lo haces en la 2.2), no lee nada. A service-role es la clave del servidor: ignora la RLS y tiene acceso total. Por eso, el rol de servicio nunca va al navegador ni a git — solo al ~/.env.
Conceptos clave
El proyecto es tuyo, en tu cuenta.
Cerca de ti = menos latencia.
Se convierte en DB_PASSWORD para las migrations.
Anon pública, service-role del servidor.
🤖 Crear el bot en Telegram (@BotFather)
Telegram es la puerta de entrada del coach: conversas por mensaje. Para que esto exista, creas un bot con el @BotFather (el "bot oficial que crea bots") y obtén su token: el HEALTH_BOT_TOKEN.
Abre @BotFather en Telegram
Busca @BotFather (el verificado, con la insignia azul) e inicia la conversación.
Envía /newbot y nombra
Elige un nombre para mostrar y un username que termine en bot (p. ej.: meu_health_os_bot).
Copia el token que te da
Viene algo como 123456789:AAH...xyz. Este es el HEALTH_BOT_TOKEN — guárdalo para el tema 6.
⚠️ El token es la llave de la puerta
Cualquiera con el HEALTH_BOT_TOKEN controla tu bot. No lo pegues en un chat ni lo subas a git. Si se filtra, usa /revoke en @BotFather para generar uno nuevo en el momento.
💡 Dónde se usa el token
Además de ~/.env, el agente apunta a esa variable en el agent.yaml (campo telegram_bot_token_env). De hecho, activas esto en la Trilha 2.3: aquí solo necesitas tener el token a mano.
Conceptos clave
El bot oficial que crea tu bot.
Comando que genera el bot y el token.
La clave de la puerta de entrada.
Cambia el token si se filtra.
🔑 Claves de OpenAI y Gemini
Dos claves cubren dos trabajos diferentes. La OpenAI genera los embeddings de la memoria (es como el coach recuerda tu historial). El Gemini (Google) hace la visión: transforma la foto de una comida o de un análisis en datos.
🟢 ¿Nuevo por aquí?
Embedding es convertir un texto en un vector de números que captura el «sentido». Los mensajes parecidos se convierten en vectores cercanos —así es como el coach encuentra lo que dijiste hace semanas (memoria semántica), en vez de guardar solo lo último que dijiste.
🧠 OPENAI_API_KEY
- •Crea en
platform.openai.com→ Claves de API. - •Usada para embeddings de la memoria semántica.
- •El costo de los embeddings es de centavos.
📸 GOOGLE_API_KEY
- •Crea en
aistudio.google.com→ Obtener clave de API. - •Visión Gemini: foto de comida → macros, análisis → marcadores.
- •Costo de centavos por foto.
💰 Cuánto cuesta
Para una persona, el uso típico ronda US$ 10–20/mes sumando las llamadas de LLM, con embeddings y visión, en centavos. Configura un límite de gasto en cada cuenta para dormir tranquilo.
Conceptos clave
OpenAI: la base de la memoria semántica.
Gemini: la foto se convierte en datos estructurados.
OpenAI y Google AI Studio.
Centavos por foto/embedding.
⌚ Cuenta WHOOP + app de desarrollo (opcional)
WHOOP es el ejemplo de wearable del blueprint, pero es 100% opcional. El mismo patrón (OAuth + sync diario) sirve para Oura, Garmin, Fitbit o el registro manual. El coach y el dashboard trabajan con lo que aparezca en la tabla vitals, venga de donde venga.
🟢 ¿Nuevo por aquí?
OAuth es el apretón de manos que permite que tu app lea tus datos en la WHOOP sin guardar tu contraseña. Autorizas una vez; WHOOP devuelve un refresh_token que el sync usa (y rota) cada mañana.
✓ Tiene WHOOP
- ✓Crea una app en
developer.whoop.com. - ✓Obtén el
WHOOP_CLIENT_IDe oWHOOP_CLIENT_SECRET. - ✓La API es gratuita con la suscripción. El
REFRESH_TOKENla callback se completa en la 2.4.
○ No tienes WHOOP
- ○Deja las tres variables
WHOOP_*vacías. - ○Usa otro wearable con el mismo patrón o registra manualmente la recuperación y el sueño.
- ○Todo lo demás del curso funciona igual.
💡 Dos trampas que la 2.4 resuelve
Cuando actives la sincronización de verdad (Ruta 2.4), hay dos cosas que pueden complicarse: Cloudflare bloquea el user-agent predeterminado de Python (envía uno de navegador) y el refresh-token debe ser rotado en cada run. Aquí solo necesitas tener las credenciales; el resto viene después.
Conceptos clave
Cualquier fuente sirve, incluso manual.
Genera CLIENT_ID y CLIENT_SECRET.
Autoriza sin guardar la contraseña.
El destino común de cualquier wearable.
📄 El archivo ~/.env
Todo lo que reuniste — token, URL, claves — converge en un único archivo: o ~/.env, en tu home (el ~ es el atajo a tu carpeta de usuario). Se encuentra fuera de git, siempre. El agente lee los secretos desde ahí para funcionar.
📊 Cómo leer: las cinco fuentes (cian, a la izquierda) vierten sus claves en un solo lugar — el ~/.env (azul, en el centro). El agente solo lee este archivo. WHOOP aparece con línea discontinua porque es opcional.
Todas las variables y para qué sirven
| Variable | Para qué |
|---|---|
| HEALTH_BOT_TOKEN | Token del bot de Telegram (de @BotFather). |
| SUPABASE_URL | Dirección de tu proyecto: https://<ref>.supabase.co. |
| SUPABASE_SERVICE_ROLE_KEY | Acceso del servidor a la base de datos (ignora la RLS). Nunca en el navegador. |
| SUPABASE_ANON_KEY | Clave pública — con RLS activada, no puede leer nada. |
| SUPABASE_DB_PASSWORD | Contraseña de la base de datos para que Supabase CLI ejecute las migrations. |
| OPENAI_API_KEY | Embeddings de la memoria semántica. |
| GOOGLE_API_KEY | Visión Gemini (foto de comida / examen / entrenamiento). |
| DASHBOARD_TOKEN | Protege el dashboard web (un secreto aleatorio tuyo). |
| WHOOP_CLIENT_ID | ID de tu app WHOOP (opcional). |
| WHOOP_CLIENT_SECRET | Secreto de tu app de WHOOP (opcional). |
| WHOOP_REFRESH_TOKEN | La escribe la callback OAuth y se rota con cada sincronización. |
# ~/.env — segredos do HealthOS. NUNCA versionar (fica na home, fora do git).
# Telegram (do @BotFather)
HEALTH_BOT_TOKEN=<seu-token-do-botfather>
# Supabase (Settings -> API e Database)
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
SUPABASE_ANON_KEY=<anon-public-key>
SUPABASE_DB_PASSWORD=<senha-do-banco>
# Modelos
OPENAI_API_KEY=<sk-...>
GOOGLE_API_KEY=<sua-chave-gemini>
# Dashboard
DASHBOARD_TOKEN=<um-segredo-aleatorio-seu>
# WHOOP (OPCIONAL — qualquer wearable ou registro manual serve)
WHOOP_CLIENT_ID=<client-id-do-app-whoop>
WHOOP_CLIENT_SECRET=<client-secret-do-app-whoop>
WHOOP_REFRESH_TOKEN=<deixe-vazio-a-callback-preenche>~/.env. La recomendación para el repo es copiar de agent/.env.example y completar. No quedó ningún <...>? Entonces está listo para el siguiente paso.# 1) o arquivo existe?
ls -l ~/.env
# 2) nenhum valor ficou como placeholder <...>?
grep -n '<' ~/.env || echo "OK: nenhum placeholder sobrando"ls debe listar el archivo (si aparece "No such file", no está en el directorio home). El grep debe imprimir OK: nenhum placeholder sobrando — si enumera filas, todavía hay <...> para intercambiar.⚠️ Nunca hagas commit del ~/.env
- •Vive en tu inicio (
~/.env), nunca en un.envdentro del proyecto. - •Fuera de Git, siempre. Quien tenga estas claves tiene acceso a tus datos de salud.
- •Si se filtra una clave, revócala y genera otra de inmediato en la cuenta de origen.
Conceptos clave
Todo converge en el ~/.env.
~/.env, no dentro del proyecto.
Los secretos nunca se versionan.
3 de ellas (WHOOP) opcionales.
✅ Lista de verificación de preparación
Antes de seguir con la base de datos (Módulo 2.2), confirma que cada pieza esté en su lugar. El diagrama de abajo muestra qué va dónde — qué clave alimenta cada capacidad del coach. Si todo eso está listo, ya puedes empezar.
📊 Cómo leer: cada clave de la izquierda (cian) conecta UNA capacidad del coach de la derecha (azul). Si falta la de la izquierda, la de la derecha no se activa. Solo la última fila (WHOOP) es opcional — sin ella, el coach funciona igual, con registro manual.
✅ Estás listo si…
- ✓
python3 --version≥ 3.9 enode --versionresponden. - ✓Proyecto privado de Supabase creado en una región adecuada; URL + 2 claves + contraseña de la base de datos guardadas.
- ✓Bot creado en @BotFather;
HEALTH_BOT_TOKENen la mano. - ✓
OPENAI_API_KEYeGOOGLE_API_KEYcreadas. - ✓(Opcional) Creaste la app de WHOOP o decidiste registrar los datos manualmente.
- ✓
~/.envarmado y verificado — sin ningún<...>sobrando.
✅ Autoevaluación (opcional): ¿dónde deben estar tus claves y secretos de HealthOS?
Conceptos clave
Cada clave activa una capacidad.
Sin la clave, la capacidad no se activa.
La única línea que puede quedar vacía.
Todo listo → vamos a la base de datos.
📋 Resumen del módulo
Próximo módulo:
2.2 — La base de datos: aplicar las migraciones en Supabase, habilitar pgvector, crear las 14 tablas y el bucket de fotos, y bloquear todo con RLS.