Deploy

LinkBrain runs entirely on Cloudflare: a single Worker, a D1 database, and Workers AI. Personal use stays inside the free tiers, and there is no long-running process — the Worker wakes on each Telegram webhook request.

Prerequisites

• A Cloudflare account (free) and Node.js 18+. npm install pulls in wrangler locally.
• A Telegram bot token — message @BotFather, send /newbot, and copy the token (looks like 7123456789:AAF…).
• (Optional) a GitHub token (classic, no scopes) — raises the GitHub API rate limit from 60 to 5,000 requests/hour. Only worth it if you save many repos.

Steps

1. Install dependencies from the project root.

   npm install

2. Authenticate wrangler with your Cloudflare account (opens a browser).

   npx wrangler login

3. Create the D1 database, then paste the printed database_id into wrangler.jsonc (replace REPLACE_WITH_ID_FROM_wrangler_d1_create).

   npx wrangler d1 create linkbrain

4. Create the tables and load seeded links.

   npx wrangler d1 migrations apply linkbrain --remote

5. Set your secrets (paste each value when prompted). Generate a webhook secret with openssl rand -hex 16.

   npx wrangler secret put TELEGRAM_TOKEN     # the BotFather token
   npx wrangler secret put WEBHOOK_SECRET     # a random string
   npx wrangler secret put ALLOWED_CHAT_ID    # your chat id — see below
   npx wrangler secret put GITHUB_TOKEN       # optional; enter to skip

6. Deploy — this prints your Worker URL.

   npm run deploy

7. Point Telegram at the Worker. The webhook lives at the /webhook path (everything else serves the docs). The secret_token MUST equal the WEBHOOK_SECRET from step 5.

   curl "https://api.telegram.org/bot<TELEGRAM_TOKEN>/setWebhook?url=https://linkbrain.<you>.workers.dev/webhook&secret_token=<WEBHOOK_SECRET>"

Finding your chat id

ALLOWED_CHAT_ID locks the bot to just you. Message @userinfobot on Telegram — it replies with your numeric id. With it set, the Worker silently ignores messages from any other chat. See the security model for what each gate stops.

Verify

Confirm the webhook is registered:

curl "https://api.telegram.org/bot<TELEGRAM_TOKEN>/getWebhookInfo"

You want "url" set to your Worker and "pending_update_count": 0 with no last_error_message. Then send a link to your bot — you should get a reply with a summary and tags within a couple of seconds.

Migrating from the original Python bot

The first version of LinkBrain was a local Python bot that long-polled Telegram. A bot can’t long-poll and use a webhook at the same time, so if the old bot is still running, stop it before calling setWebhook.

Local development

npm run dev                  # wrangler dev on http://localhost:8787
npm run db:migrate:local     # apply migrations to the LOCAL D1

D1 runs locally, but Workers AI has no local engine — wrangler dev proxies AI calls to your Cloudflare account, so summaries need wrangler login. Without it, summarization degrades gracefully and the link still saves from scraped metadata. Local secrets live in .dev.vars (gitignored).