tbucket.app

install guide/20–30 minutes/re-run safe

Install tbucket

This page is the whole install, spelled out. Most of the work is done by a guided script — you double-click one file, answer its questions, and it builds your deployment on your own accounts, testing each key as you paste it. Keep this page open on a second screen and follow along.

Before you start: two accounts that run it

Everything runs on accounts you own. Make these first if you don't have them:

  1. Cloudflare — where your copy of tbucket runs and where your notes live. The free tier covers it, with one heads-up: on a new account, Cloudflare asks you to activate R2 (its file storage, where your voice notes and photos live) before first use, and activation wants a payment method on file. It stays free — this workload costs $0. Activate it now to save a pause later: dashboard → R2 → Get started. dash.cloudflare.com/sign-up
  2. OpenRouter — the AI billing account. The models that tag your notes and read your photos run under your own key here, a few dollars a month. Add a small prepaid credit ($5 is plenty to start). openrouter.ai

You'll also need a GitHub account (github.com/signup) — with your license it receives access to the tbucket code repository, which is how you get the code and updates. This page is public, the code isn't. GitHub can also hold a synced copy of your notes for Obsidian — that part is optional, connectable from the app whenever you want it, and covered at the bottom of this page.

Step 1 — Install two small tools

  1. Node (the runtime the installer uses): download the LTS installer from nodejs.org and click through it. Defaults are fine.
  2. GitHub Desktop (how you get the code and, later, updates — no command line): desktop.github.com. Install it and sign in to your GitHub account.

Step 2 — Get the code

  1. In GitHub Desktop: File → Clone repository, pick the tbucket repository from the list (it appears once your access is granted; an older grant may still list it under its previous name, thoughtnet), choose where to put it, clone.
  2. That folder is now your copy. Remember where it is.

Step 3 — Double-click setup

  1. Open the cloned folder and double-click setup.cmd (Windows) or setup.command (Mac).
  2. A terminal window opens and takes over. If Node is missing it says so and opens the download page; otherwise it installs the one pinned dependency and begins.

Mac may warn about an unidentified developer the first time — right-click the file, Open, Open. If you'd rather use a terminal: npm run setup from the folder does the same thing.

Step 4 — Answer the prompts

The script walks these in order. Nothing is destructive and it's safe to re-run from the top if anything is interrupted — it detects what already exists.

  1. Cloudflare login. A browser window opens; click Allow. That's the whole login.
  2. Personalize. A one-line "who is this brain for" blurb (the AI uses it for context), your timezone (it guesses; Enter accepts), and a name for your brain — naming it is the fun part, and the name becomes your personal URL.
  3. It builds. Database, media storage, schema, first deploy — a minute or two of output ends with your personal URL, something like https://mybrain.yourname.workers.dev. Two first-time-account moments are normal here: if the script stops saying R2 is not activated, do the R2 activation from the accounts step above and double-click setup again; and on the very first deploy Cloudflare asks you to register a workers.dev subdomain — that's the yourname part of your URL. Pick something short you like; every app you ever deploy on that account uses it.
  4. Secrets. The script generates your app token itself, then asks you to paste your OpenRouter key. It is tested the moment you paste it — a mistyped or dead key gets a plain-English fix-it message right there, not a mystery later. (If someone is helping you over a screenshare, this is the step where you pause sharing.) Notice what it does not ask for: no GitHub anything — notes live on your Cloudflare from the start, and the GitHub sync is an optional connect later, from the app.
  5. Reminders (optional). Say yes, give it a contact email (the push service requires one), and captured "remind me at four" items will push real notifications to your phone. You can also say no and turn it on later.

Step 5 — Put it on your phone

  1. Open your personal URL (from step 4) in Chrome (Android) or Safari (iPhone).
  2. Paste the app token when asked — the script printed it at the end, clearly marked. It's stored only on the device.
  3. Browser menu → Add to Home screen. The red button is now one tap away.
  4. Tap it. Say something. Watch the echo come back.

On Android, there's an upgrade: a native tbucket app with a real home-screen record-button widget (one tap from anywhere straight into the mic), share-to-tbucket from any app, an offline capture queue, and reminder alarms that need no push server. Download the .apk from the code repository's Releases page — the same access you cloned with in step 2 covers it — open it, allow the install when Android asks, and enter the same URL + token. Full steps: android/README.md in the repo. Run either version, or both.

Later, optional — GitHub sync and Obsidian

You're done: capture, search, the graph, and ask all live in the app, and your notes live on your Cloudflare. Two optional power-ups whenever you want them:

  1. Download your brain. In the app: Settings → export. The notes zip is instant and opens directly in Obsidian as a vault; photos and audio download alongside it by month. No accounts involved — it's your file the moment it lands.
  2. Connect GitHub for live sync. In the app: Settings → github vault. The card walks you through it with two links: create a new private repository (github.com/new, name it tbucket-vault, no readme needed), then generate a fine-grained token from the pre-filled link the card gives you — the one thing the pre-fill can't do is pick the repository, so under "Repository access" choose Only select repositories and select just your vault. Paste both into the card. The token is tested the moment you paste it, a public repository is refused outright (your notes are not allowed to be world-readable), and then everything you have ever captured backfills into the repository automatically — the card shows the count as it syncs.
  3. Open it in Obsidian. Install Obsidian (free, obsidian.md), clone your tbucket-vault repository in GitHub Desktop the same way as step 2, open that folder as a vault, install the community plugin Obsidian Git, and enable auto-pull. Captures from your phone appear within a couple of minutes — graph, backlinks, search, audio playback, all of it, with full version history.

Updating, later

When an update ships: double-click update.cmd / update.command in the code folder. It applies any database changes, then redeploys — the one safe order, automated. If it says git isn't available on your machine, pull the latest in GitHub Desktop first (Repository → Pull), then let it continue — it still handles the rest. If it complains about conflict markers in wrangler.toml, open that file, keep YOUR values, take any new lines, delete the marker lines, and run it again. Your notes are never touched by updates. On the native Android app, an update is just a newer .apk from the same Releases page — it installs over the old one in place.

If something goes wrong

The script stopped or I closed it by accident.
Double-click setup again. Every step checks what already exists and skips ahead; nothing is created twice.
A re-run asked "rotate the device token?"
Answer y if you never reached the final screen that printed your token — it mints a fresh one and prints it this time. Answer n if your phone is already set up and working: rotating logs every device out until the new token is re-entered.
It rejected my GitHub token (when connecting the optional vault).
The message says exactly why — usually the token wasn't scoped to the vault repository, or Contents wasn't set to Read and write. Generate a fresh one with those two settings and paste it into the card again.
I need to redo just the keys.
Run node scripts/provision.mjs --secrets-only from a terminal in the folder. It re-does only the secrets step against your existing deployment.
Something else.
Get in touch — it reaches the person who built this, not a ticket queue. Say which step you were on and what the screen said, and you'll get a real answer.