Tvix for Mac

Run the same Tvix product on your Mac. Memories and connectors stay on this machine under ~/Library/Application Support/Tvix. Your account is your tvix.ai portal identity.

Requirements

• macOS 13+
• Docker Desktop for Mac
• An OpenAI API key (embeddings / extract / chat)
• A tvix.ai account (sign up on the web portal)
• Optional: Google Calendar / Gmail / Drive (connected via tvix.ai in your browser — no localhost OAuth client)

Install

1. Download Tvix for Mac from Settings or tvix.ai/downloads.
2. Open the Mac app wizard: Docker → OpenAI key → Start.
3. First launch downloads prebuilt Tvix runtime images from Docker Hub (no source code on your Mac, no local Docker build). That download is typically a few hundred MB and can take a few minutes.
4. Click Open Mac app — your browser opens https://tvix.ai/open-local?client=mac (not the local login form).
5. Sign in on tvix.ai if needed. The portal mints a one-time link and opens tvix://local-callback. If the Mac app doesn’t come forward, click Return to Mac app.
6. Data stays on the Mac; only identity comes from the portal.

To pull newer runtime images later (without reinstalling the Mac app):

~/Library/Application\ Support/Tvix/app/local/scripts/tvix-local.sh update

Do not enable DEMO_MODE_ENABLED for the Mac app.

How login works

Mac app / Open Mac app  →  https://tvix.ai/open-local?client=mac
You                     →  sign in on tvix.ai (if needed)
Portal                  →  mint → tvix://local-callback?exchange_token=…
Mac app                 →  deep link → /auth/local-callback → local JWT → /chat

Cloud JWTs are not reused on the Mac API (different database and signing key). Same email / account, local session.

http://127.0.0.1:3000 is only used for the post-auth handoff (/auth/local-callback) and the Mac app UI itself — not as the login start.

Advanced: if tvix.ai is unreachable, Mac /login exposes an offline Mac-only account option under Advanced.

Google connectors (Calendar / Gmail / Drive)

Connect from Sources in the Mac app:

Mac Sources → Connect Google
  → system browser opens https://tvix.ai/local-connect/google?client=mac
  → sign in on tvix.ai if needed → consent at Google (HTTPS redirect on api.tvix.ai)
  → portal page → tvix://local-callback?connector_exchange=…
  → Mac app stores tokens locally and syncs

You do not paste a Google Client ID/Secret or configure localhost redirect URIs. Authorization uses Tvix’s hosted Google OAuth client; tokens are stored only on your Mac after a one-time handoff.

If the browser doesn’t return to the Mac app automatically, click Return to Mac app on the portal done page.

Advanced (optional): Settings → Google → “custom Google Cloud OAuth client” if you deliberately want a private client — not the normal Mac path.

Inspect memories (nodes and edges)

Open Memories → Inspect for the real Postgres graph (not the curated mind-map Graph tab):

• Visual — force graph of memories + graph_edges
• Raw — tables for memories, edges, and memory_events, plus Download/Copy JSON

On-disk markdown mirror (when enabled): ~/Library/Application Support/Tvix/memory_store (includes events.jsonl). Finder → Go → Go to Folder.

Wiki folders from knowledge memories

Knowledge memories (TKF cognify / capture) create Wiki theme folders and matching notes — not raw Gmail/Drive dumps. New syncs update them in place.

To backfill after an upgrade:

./local/scripts/tvix-local.sh wiki-backfill

To wipe derived knowledge and re-cognify from stored artifacts:

./local/scripts/tvix-local.sh memory-rebuild --user-email you@example.com
# Preview:  ./local/scripts/tvix-local.sh memory-rebuild --dry-run --user-email you@example.com

Or in the app: Wiki → Sync wiki from memories. Artifacts and connector tokens are kept.

Connect agents (MCP)

On Mac, agents must talk to the local API — not cloud api.tvix.ai — or they will not see on-device memories.

Local MCP URL (Bearer clients): http://127.0.0.1:8000/mcp

1. In the Mac app UI, open Agents → + Add Agent and pick your client.
2. For Cursor / Claude / VS Code: copy the generated config (uses localhost + Bearer). No tunnel needed.
3. Or mint a token and print a Cursor snippet:

./local/scripts/tvix-local.sh mcp-snippet et_YOUR_TOKEN

ChatGPT / Poke (OAuth — needs HTTPS)

ChatGPT rejects localhost. On the Mac app:

1. Agents → ChatGPT → Enable remote agents (or ./local/scripts/tvix-local.sh start-mcp-tunnel).
2. Copy the HTTPS MCP URL the wizard shows into ChatGPT / Poke (OAuth) and complete consent.

Connecting ChatGPT to cloud api.tvix.ai will not see Mac-local memories.

Claude Desktop: use the mcp-remote config from the wizard. Node 18 crashes with File is not defined; use Node 20.18.1+.

Full per-client steps: Quickstart and Cursor.

Cloud config note

Hosted api.tvix.ai must allow CORS from http://127.0.0.1:3000 for Mac→cloud link calls (see deploy/.env.production.example). Portal mint runs on tvix.ai against the cloud API.

Troubleshooting

• Doesn’t return to Mac app — after mint, click Return to Mac app on the portal page (browsers often block automatic tvix:// opens). Ensure /Applications/Tvix for Mac.app is installed (not an old “Tvix Local” build without the URL scheme). Then open https://tvix.ai/open-local?client=mac again.
• Redirect fails / blank Mac UI — start the Mac app first; then open https://tvix.ai/open-local?client=mac again.
• First Start stuck on “Downloading Tvix runtime images” — confirm Docker Desktop is running and you can reach Docker Hub (docker pull hello-world). Then retry Start, or run tvix-local.sh update from Application Support.
• Provision / exchange failed — token expired (~10 min) or cloud unreachable; retry from tvix.ai.
• Calendar / Google connect — use Sources → Connect; complete consent in the browser, then Return to Mac app if needed. Unrelated to portal login.
• Agent connected but empty memory — confirm MCP URL is http://127.0.0.1:8000/mcp, not https://api.tvix.ai/mcp.
• ChatGPT rejected URL — localhost/HTTP is blocked; use an HTTPS tunnel pointed at the Mac API.