Deploy to Cloudflare (Workers + static assets)#

One Worker serves all of vid2context.com:

Path	What
`/` and `/docs/*`	the landing site (`site/`)
`/app/`	the web app (`packages/web`), when it builds
`/chat/`	the chat app (`packages/chat`), when it builds
`/api/v1/*`	the HTTP API (`packages/server`)
`/mcp`	remote MCP, once `packages/server/src/workers.ts` routes it (prompt 46)
`/llms.txt`, `/llms-full.txt`	the repo's LLM-readable docs

The config is the root wrangler.jsonc; the Worker entry is packages/server/src/workers.ts; static files come from dist/assets/, built by npm run build:assets.

Commands#

npm run build:assets            # assemble dist/assets (site, apps that build, llms.txt)
npm run dev:worker              # build assets, then wrangler dev on http://localhost:8787
npm run deploy                  # build assets, then wrangler deploy (needs CLOUDFLARE_API_TOKEN)
npx wrangler deploy --dry-run --outdir dist/worker   # bundle and validate without uploading

build:assets skips an app that is missing or does not build, and says why. Add -- --strict to make that an error (do this for production once packages/web and packages/chat exist): npm run build:assets -- --strict && npx wrangler deploy.

A dry run on 2026-11-14 bundled the Worker to 120 KiB (33 KiB gzipped); the free plan allows 3 MiB compressed. No nodejs_compat flag is needed: the Workers registry contains only fetch-based providers.

Credentials#

wrangler deploy needs a Cloudflare API token with the "Edit Cloudflare Workers" template, in CLOUDFLARE_API_TOKEN (and CLOUDFLARE_ACCOUNT_ID if the token can see several accounts). Put both in .env or your shell; never in wrangler.jsonc.

Secrets and variables#

Provider keys and API keys are Worker secrets, set once per key:

npx wrangler secret put GROQ_API_KEY
npx wrangler secret put GEMINI_API_KEY
npx wrangler secret put VID2CONTEXT_API_KEYS     # comma-separated keys for /api/v1 when the API should not be open

Every variable in .env.example works the same way. wrangler.jsonc sets one plain variable, VID2CONTEXT_PUBLIC=1, which marks this deployment as the public, internet-facing instance.

Optional bindings#

All are commented out in wrangler.jsonc. Without them the Worker keeps the library in memory (per isolate), uses hosted and keyless rungs, and runs no background jobs. To turn one on, create the resource, uncomment its block, and uncomment the matching variable in vars (the storage provider reads the variable to find the binding).

Binding	Create with	Variable	Used by
D1 `DB`	`npx wrangler d1 create vid2context`	`VID2CONTEXT_D1=DB`	the library: contexts, collections, search (providers/storage-cloudflare)
R2 `MEDIA`	`npx wrangler r2 bucket create vid2context-media`	`VID2CONTEXT_R2=MEDIA`	large contexts and uploads
KV `KV`	`npx wrangler kv namespace create vid2context`	`VID2CONTEXT_KV=KV`	KvStore: sessions, API keys, webhooks, caches
Workers AI `AI`	nothing to create	none	free Whisper and LLM rungs through the binding (providers/cloudflare-ai)
Queue `JOBS_QUEUE`	`npx wrangler queues create vid2context-jobs`	none yet	background jobs (packages/jobs); needs a `queue` handler in the Worker entry
Cron trigger	nothing to create	none	watch-list refresh (prompt 41); needs a `scheduled` handler in the Worker entry

Free limits that matter (Workers Free plan, as published by Cloudflare): 100,000 requests per day, 10 ms CPU per request (I/O wait such as calling YouTube or an LLM does not count), D1 5 GB, R2 10 GB, KV 100,000 reads per day, Workers AI 10,000 neurons per day. Long speech-to-text jobs belong on Node or in a queue consumer, not in a request.

What runs on Workers#

Works	Does not
YouTube metadata and captions (innertube, plain fetch)	yt-dlp, ffmpeg, whisper.cpp and other binaries
Hosted and keyless speech-to-text for uploads within each rung's size limit	Local files (there is no filesystem; the media-file source is not in the Workers registry)
Every LLM rung that speaks HTTP, including keyless OVH and Pollinations	Local models (Ollama, LM Studio) unless exposed over HTTPS
Workers AI through the `AI` binding	Long-audio splitting (needs ffmpeg)

YouTube blocks many datacenter IPs. Cloudflare's egress IPs are shared and sometimes rate-limited: when captions fail with blocked, the API says so with a hint. A Cloudflare Tunnel to a machine at home (see the remote MCP guide) avoids that.

Domain#

vid2context.com and www.vid2context.com are custom domains in routes; Cloudflare creates the DNS records and certificates on the first deploy. The Worker redirects www. to the bare domain.
vidtocontext.com: add it to the same Cloudflare account, then create a redirect rule (Rules, Redirect Rules, "Redirect from root to WWW" style, custom): when hostname equals vidtocontext.com or www.vidtocontext.com, redirect to https://vid2context.com${path} keeping the query string, status 301. The zone needs a proxied DNS record (for example an A record to 192.0.2.1, proxied) so requests reach the rule.
vid2context.<account>.workers.dev stays on as a fallback URL (workers_dev: true).

SPA routing for the apps#

/app/* and /chat/* deep links must serve each app's index.html. Workers static assets cannot do this per path: not_found_handling is global, and _redirects rewrites apply even when a file exists, so /app/* /app/index.html 200 would also rewrite the app's own JavaScript. The Worker does it instead with fetchAssetWithSpaFallback from deploy/serverless/cloudflare/spa-fallback.ts: assets first, and only on a 404 for a non-file path under an app mount, that app's index. It is verified in the Workers runtime by deploy/serverless/test/worker.test.ts (WRANGLER_TEST=1). Wiring it into packages/server/src/workers.ts is one line, listed for prompt 46.

Verify a deploy#

curl https://vid2context.com/api/v1/health
curl "https://vid2context.com/api/v1/transcript?url=https://youtu.be/jNQXAC9IVRw&timestamps=1"
npx wrangler tail          # live logs