Setup & keys — from git clone to talking
Everything a developer needs to stand up their own Watari: install, get every key, integrate each component, and run the tests. TODO-NOW.md in the repo is the exhaustive, copy-paste version of this page.
0 · Prerequisites
- Python 3.11+ and uv.
- Node 18+ only if you also build this docs site.
- Tailscale on every device for a multi-device deploy (see Networking).
- An always-on host (a small Linux VPS) if you want the 24/7 brain.
1 · Clone & install
git clone https://github.com/iamvazghen/OpenWatari openwatari
cd openwatari
uv sync --extra edge --extra cloud-voice --extra brain --extra channels --extra identity --extra dev
uv run jarvis-setup # interactive .env generator2 · Get the keys
All keys live in .env (prefix JARVIS_). Everything degrades gracefully — set only what you want. Required to function: a voice (TTS), an ear (STT), a brain (LLM), and the vault path.
| Component | Key(s) | Where to get it | Tier |
|---|---|---|---|
| TTS voice | JARVIS_ELEVENLABS_API_KEY, _VOICE_ID | elevenlabs.io → Profile → API key; pick a voice, copy its ID (or use local Piper, no key) | Required |
| STT | JARVIS_DEEPGRAM_API_KEY | deepgram.com (free tier). For Armenian/Ukrainian use local Whisper instead (no key) | Required |
| Brain LLM | JARVIS_FREELLMAPI_BASE_URL + _API_KEY | any OpenAI-compatible endpoint: a free proxy, OpenAI (api.openai.com/v1), or local Ollama | Required |
| Vault (L3 memory) | JARVIS_VAULT_PATH | path to your Obsidian/Markdown folder; JARVIS_VAULT_WRITABLE=true only on the host that owns it | Required |
| Web search | JARVIS_TAVILY_API_KEY | tavily.com (scraping uses keyless Jina Reader) | Recommended |
| Telegram | JARVIS_TELEGRAM_API_ID, _API_HASH, _BOT_TOKEN, _PHONE | my.telegram.org (api id/hash) + @BotFather (bot token); then uv run python bench/telegram_login.py once | Recommended |
| Gmail + Calendar | JARVIS_GOOGLE_CLIENT_ID, _SECRET, _REFRESH_TOKEN | console.cloud.google.com: enable Gmail + Calendar APIs, make a Web OAuth client, add the redirect, then uv run python bench/google_login.py | Recommended |
| Notion | JARVIS_NOTION_TOKEN | notion.so/my-integrations → internal integration; share the pages you want it to touch | Optional |
| Home Assistant | JARVIS_HA_URL, JARVIS_HA_TOKEN | HA → Profile → Security → long-lived access token | Optional |
| Phone push | JARVIS_NTFY_TOPIC | pick an unguessable string; subscribe to it in the ntfy app | Recommended |
| Self-improvement push | JARVIS_GITHUB_TOKEN, JARVIS_GITHUB_REPO | github.com/settings/tokens → fine-grained PAT, Contents: read/write on your repo | Optional |
| Cloud browser | JARVIS_BROWSERBASE_API_KEY, _PROJECT_ID | browserbase.com (the local visible browser needs no key) | Optional |
| Custom wake phrase | JARVIS_PORCUPINE_ACCESS_KEY | console.picovoice.ai (the pre-trained phrases need no key) | Optional |
The wizard auto-generates the multi-device
JARVIS_API_AUTH_TOKEN and all eightJARVIS_PROTOCOL_*_PASSWORD values for you — you don't fetch those anywhere.3 · Integrate the components
- Vault — point
JARVIS_VAULT_PATHat your notes; it's validated at startup. - Telegram / Google — run the one-time login helpers in
bench/(they print a token or create a session file). - Redis (optional L4) — set
JARVIS_REDIS_URL; otherwise an in-process cache is used. - Semantic recall (optional L5) —
uv pip install sentence-transformers(downloads a ~90 MB CPU model on first use). - Multi-device — Tailscale on every device, then set
JARVIS_BRAIN_HOST=0.0.0.0and the brain WS URL to the tailnet IP (the wizard's vps mode does this). - Voice enrollment —
uv run python bench/enroll_voice.py --script "to-read-script.md", thenJARVIS_SPEAKER_ID_ENABLED=true.
4 · Run the tests
uv run python bench/run_all_tests.py # the single gate (offline; SKIP != FAIL)
uv run python bench/check_config.py # which keys are set
uv run python bench/efficiency_report.py # hot-path latency vs targets
uv run python bench/test_live_integrations.py # exercises the keys you actually set5 · Run it
uv run python -m jarvis.edge.assistant # local voice loop
uv run python -m jarvis.brain.server # the shared 24/7 brain (phone/glasses)Then see Production readiness for the go-live checklist, and edit personality/jarvis.md to make it yours.