Module 2.1 — Prerequisites and accounts

🐍 What to install on your machine

HealthOS is intentionally lean: the scripts are Pure Python (stdlib) — only the advice.py asks for pip install requests. Before creating any accounts, get four basic tools ready on your machine. Install them once, then move on to the rest.

🟢 New here? Two terms before you continue

CLI — “command-line interface”: a program you run by typing in the terminal, with no graphical window. The Supabase CLI is what pushes the database to the cloud with a command.
Runtime — the "engine" that runs a type of code. Python runs the scripts; Node runs the agent and the dashboard server.

📊 How to read: the four core tools (cyan, on the left) only need to be installed once. Python and Node are required; ffmpeg is only needed if you're generating workout clips; the Supabase CLI pushes the database in Track 2.2.

Tool	Required?	Purpose
Python 3.9+	Yes	Runs the scripts (stdlib). Only `advice.py` uses `pip install requests`.
Node	Yes	Runs the agent and the dashboard server.
ffmpeg	Optional	Only for `exercise_clip.py` (workout demo clips).
Supabase CLI	Yes	Pushes the migrations (creates the 14 tables)—used in 2.2.

▶Goal: confirm that Python and Node are installed (and at the right versions)

python3 --version && node --version

How to verify: should print two lines, e.g.: Python 3.11.6 e v20.11.0. If Python shows a version below 3.9 or returns “command not found,” install/update it before continuing. (ffmpeg and Supabase CLI: check with ffmpeg -version e supabase --version — the first one only if you’re going to use clips.)

Key concepts

Stdlib

The scripts don't depend on external packages (almost nothing to install).

Python + Node

The two required engines: scripts and agent.

optional ffmpeg

Only for workout clips.

Supabase CLI

Pushes the database—the star of 2.2.

☁️ Create the private Supabase project

O Supabase is where ALL your health data will live—food, workouts, weight, tests, vital signs, goals, and message history. That’s why it has to be private, in your account. Here you just create the project and save four secrets; creating the tables is step 2.2.

🟢 New here?

Supabase is a cloud PostgreSQL database + file storage, with a web dashboard. Think of it as the “coach’s hard drive”: everything you log becomes a row there, and the agent reads from it in every conversation.

Create an account and a new project

In supabase.com, “New project.” The plan free is enough for one person.

Choose a suitable region

Choose the region closest to you (lower latency). For Brazil, usually South America (São Paulo).

Set and save the database password

The bank password becomes the SUPABASE_DB_PASSWORD — the Supabase CLI will need it in 2.2 to push the migrations.

Copy the URL and keys (Settings → API)

Get the SUPABASE_URL, a SUPABASE_ANON_KEY (public) and SUPABASE_SERVICE_ROLE_KEY (server). Save it for topic 6.

🔒 Anon × Service-role — two keys, two worlds

A anon is public; with RLS enabled and no policies (you do this in 2.2), it can’t read nothing. A service-role is the server key: it bypasses RLS and has full access. That’s why the service-role never goes to the browser or git — only to ~/.env.

Key concepts

Private

The project is yours, in your account.

Region

Closer to you = lower latency.

Database password

Turns into DB_PASSWORD for the migrations.

URL + 2 keys

Public anon key, server service-role key.

🤖 Create the bot on Telegram (@BotFather)

Telegram is the entry point for the coach: you chat by message. To make that possible, you create a bot with the @BotFather (the official "bot that creates bots") and get its token — the HEALTH_BOT_TOKEN.

Open @BotFather in Telegram

Search for @BotFather (the verified one, with the blue check) and start the conversation.

Send `/newbot` and name

Choose a display name and a username ending in bot (e.g., meu_health_os_bot).

Copy the token it gives you

It looks something like 123456789:AAH...xyz. This is the HEALTH_BOT_TOKEN — save it for Topic 6.

⚠️ The token is the key to the door

Anyone with the HEALTH_BOT_TOKEN controls your bot. Don't paste it into chat or push it to git. If it leaks, use /revoke in @BotFather to generate a new one right away.

💡 Where the token is used

Beyond ~/.env, the agent points to that variable in the agent.yaml (field telegram_bot_token_env). You’ll actually connect this in Track 2.3—here, just have the token handy.

Key concepts

@BotFather

The official bot that creates your bot.

/newbot

Command that generates the bot and token.

HEALTH_BOT_TOKEN

The key to the front door.

/revoke

Replace the token if it leaks.

🔑 OpenAI and Gemini keys

Two keys cover two different jobs. The OpenAI generates the embeddings from memory (it's how the coach remembers your history). The Gemini (Google) does the view: turns a photo of food or a lab test into data.

🟢 New here?

Embedding is to turn text into a vector of numbers that captures its “meaning.” Similar messages become nearby vectors—that’s how the coach finds what you said weeks ago (semantic memory) instead of only storing the latest message.

🧠 OPENAI_API_KEY

•Create it in platform.openai.com → API keys.
•Used for embeddings of semantic memory.
•Embedding costs are cents.

📸 GOOGLE_API_KEY

•Create it in aistudio.google.com → Get API key.
•Vision Gemini: food photo → macros, lab test → markers.
•Cost of cents per photo.

💰 How much it costs

For one person, typical usage is around US$ 10–20/month adding up the LLM calls, with embeddings and vision costing cents. Set a spending limit on each account so you can rest easy.

Key concepts

Embeddings

OpenAI: the foundation of semantic memory.

Vision

Gemini: photo becomes structured data.

Two accounts

OpenAI and Google AI Studio.

Cheap

Cents per photo/embedding.

⌚ WHOOP account + dev app (optional)

WHOOP is the wearable example in the blueprint, but it’s 100% optional. The same pattern (OAuth + daily sync) works for Oura, Garmin, Fitbit — or manual logging. The coach and dashboard work with whatever lands in the table vitals, wherever it comes from.

🟢 New here?

OAuth is the handshake that lets your app read your data from WHOOP without store your password. You authorize it once; WHOOP returns a refresh_token that the sync uses (and rotates) every morning.

✓ Has WHOOP

✓Create an app in developer.whoop.com.
✓Get the WHOOP_CLIENT_ID e o WHOOP_CLIENT_SECRET.
✓The API is free with the subscription. The REFRESH_TOKEN the callback fills it in at 2.4.

○ No WHOOP

○Leave the three variables WHOOP_* empty.
○Use another wearable with the same pattern, or log recovery/sleep manually.
○Everything else in the course works the same way.

💡 Two gotchas that 2.4 fixes

When you actually turn on sync (Track 2.4), two things can trip you up: Cloudflare bans Python’s default user agent (send a browser one), and the refresh token needs to be rotated on every run. Here you just need the credentials—the rest comes later.

Key concepts

Optional

Any source works, even manual entry.

Dev app

Generates CLIENT_ID and CLIENT_SECRET.

OAuth

Authorizes without storing a password.

vitals table

The common destination for any wearable.

📄 The ~/.env file

Everything you've gathered — token, URL, keys — converges into a single file: o ~/.env, in your home directory (the ~ is the shortcut to your user folder). It is outside git, always. The agent reads the secrets from there to work.

📊 How to read: the five sources (cyan, on the left) pour their keys into one place — the ~/.env (blue, in the center). The agent reads only from this file. WHOOP is dashed because it’s optional.

All the variables and what they’re for

Variable	Purpose
HEALTH_BOT_TOKEN	Telegram bot token (from @BotFather).
SUPABASE_URL	Your project URL: `https://<ref>.supabase.co`.
SUPABASE_SERVICE_ROLE_KEY	Server access to the database (bypasses RLS). Never in the browser.
SUPABASE_ANON_KEY	Public key — with RLS enabled, it can’t read anything.
SUPABASE_DB_PASSWORD	Database password for the Supabase CLI to run migrations.
OPENAI_API_KEY	Semantic memory embeddings.
GOOGLE_API_KEY	Gemini vision (food / lab test / workout photo).
DASHBOARD_TOKEN	Protects the web dashboard (a random secret of your own).
WHOOP_CLIENT_ID	Your WHOOP app ID (optional).
WHOOP_CLIENT_SECRET	Your WHOOP app secret (optional).
WHOOP_REFRESH_TOKEN	Written by the OAuth callback, rotated at every sync.

▶Goal: create the complete ~/.env (replace the parts in <...> with your values)

# ~/.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>

How to verify: save as ~/.env. The repo tip is to copy from agent/.env.example and fill it in. There aren't any <...>? Then you’re ready for the next step.

▶Goal: confirm that the file exists and the keys are filled in

# 1) o arquivo existe?
ls -l ~/.env

# 2) nenhum valor ficou como placeholder <...>?
grep -n '<' ~/.env || echo "OK: nenhum placeholder sobrando"

How to verify: o ls should list the file (if you get "No such file," it's not in the home directory). The grep should print OK: nenhum placeholder sobrando — if it lists rows, there’s still <...> to switch.

⚠️ Never commit ~/.env

•It lives in your home (~/.env), never in a .env within the project.
•Always outside Git. Anyone with these keys has access to your health data.
•If a key is exposed, revoke/regenerate it in the source account immediately.

Key concepts

One file

Everything converges in ~/.env.

On the home page

~/.env, not inside the project.

Outside Git

Secrets are never version-controlled.

11 variables

3 of them (WHOOP) are optional.

✅ Readiness checklist

Before moving on to the database (Module 2.2), confirm that every piece is in place. The diagram below shows what goes where — which key powers which coach capability. If all of this is in place, you’re ready.

📊 How to read: each key on the left (cyan) connects ONE coach capability on the right (blue). If the one on the left is missing, the one on the right doesn’t light up. Only the last row (WHOOP) is optional — without it, the coach works the same way, with manual logging.

✅ You’re ready if…

✓python3 --version ≥ 3.9 e node --version respond.
✓Private Supabase project created in a suitable region; URL + 2 keys + database password saved.
✓Bot created with @BotFather; HEALTH_BOT_TOKEN in your hand.
✓OPENAI_API_KEY e GOOGLE_API_KEY created.
✓(Optional) WHOOP app created, or you chose manual logging.
✓~/.env built and verified — with no <...> left over.

✅ Self-check (optional): where should your HealthOS keys and secrets live?

Key concepts

What goes where

Each key enables a capability.

Missing = erased

Without the key, the capability won't activate.

WHOOP optional

The only line that can be empty.

Ready for 2.2

Everything is up → let's move on to the database.

📋 Module summary

✓

Install the basics — Python 3.9+ and Node (required), ffmpeg (clips only), and Supabase CLI. Scripts use the standard library; only advice.py requires requests.

✓

Create the accounts — private Supabase (URL + 2 keys + password), bot on @BotFather (token), OpenAI (embeddings), and Gemini (vision).

✓

WHOOP is optional — any wearable or manual log works; everything goes into the vitals table.

✓

Everything converges in ~/.env — a file in your home directory, outside git; the agent reads the secrets from there.

✓

What goes where — each key enables a coach capability; without it, that part won’t work.

Next module:

2.2 — The database: apply the migrations in Supabase, enable pgvector, create the 14 tables and photo bucket, and lock everything down with RLS.

← Back to Step by step Next module →

🐍 What to install on your machine

Key concepts

☁️ Create the private Supabase project

Create an account and a new project

Choose a suitable region

Set and save the database password

Copy the URL and keys (Settings → API)

🔒 Anon × Service-role — two keys, two worlds

Key concepts

🤖 Create the bot on Telegram (@BotFather)

Open @BotFather in Telegram

Send /newbot and name

Copy the token it gives you

⚠️ The token is the key to the door

💡 Where the token is used

Key concepts

🔑 OpenAI and Gemini keys

🧠 OPENAI_API_KEY

📸 GOOGLE_API_KEY

💰 How much it costs

Key concepts

⌚ WHOOP account + dev app (optional)

✓ Has WHOOP

○ No WHOOP

💡 Two gotchas that 2.4 fixes

Key concepts

📄 The ~/.env file

All the variables and what they’re for

⚠️ Never commit ~/.env

Key concepts

✅ Readiness checklist

✅ You’re ready if…

Key concepts

📋 Module summary

Next module:

Send `/newbot` and name