tiny-vercel

Start your own tiny.technology on Vercel — personal AIs anyone can create by chatting, with devices, memory, passkeys and (optionally) payments. This is the production codebase, distilled into a template you own.

Docs: https://cagataycali.github.io/tiny-vercel/ · Live demo: https://tiny-vercel-scratch.vercel.app · Deploy walkthrough (15 min): docs/DEPLOY.md

What you get

• Personal AIs ("tinys") — /<slug> is a living AI: system prompt, knowledge, tools, memory, a public profile card, vCard/QR and Open Graph image. Visitors chat with it; the owner shapes it by chatting too.
• Agent loop — POST /api/chat streams Server-Sent Events from a Strands agent with ~35 built-in tools (memory, learnings, web, devices, scheduling, community, media, voice) and per-user model choice (OpenAI, Bedrock, Gemini, Vercel AI Gateway or bring-your-own key).
• Identity — GitHub OAuth for the first login, WebAuthn passkeys after that, a CLI token flow for daemons, HS256 session cookie.
• Devices — enroll laptops, phones, ESP32 e-ink displays, robot arms or any HTTP endpoint; relay envelopes, heartbeats, endpoint chat, task results, transcripts and Web Push all live here. Watch one come online without hardware: examples/echo-device is a 90-line endpoint device you can enroll in three commands. Wire protocol: docs/CONTRACTS.md.
• Memory graph, universe, community — vector search over every public tiny, per-user learnings, share links, follows, reputation.
• Payments (off by default) — x402 quotes, USDC wallet, ERC-8004 registration; every route answers 404 until PAYMENTS_ENABLED=true on both sides.

Shape

| Path | What | Runs on | |------|------|---------| | apps/web | Next.js 16 App Router — every page, every app/api/* route, the tools | Vercel | | apps/worker | Cloudflare Worker — D1 (SQL), KV, Vectorize, R2, a Durable Object for voice, a 1-minute cron | Cloudflare | | packages/contracts | Shared TypeScript wire protocol: SSE events, device relay envelopes, notification payloads, x402 quotes — the ABI iOS, the CLI (apps/cli) and firmware depend on | both | | apps/cli | npx tiny-vercel — the same CLI the production fleet runs (tiny-tech), pointed at your deployment with one init: MCP server for Claude Code / Cursor / Codex, a local Strands agent (TUI, REPL, voice), and the device daemon (heartbeat, relay, LAN mesh, menu bar). docs/CLI.md | your laptop | | examples/echo-device | the smallest endpoint device (telemetry / chat / snapshot behind a bearer) + an enroll script that walks the CLI consent flow | your laptop | | scripts/ | bootstrap-cloudflare.mjs creates the worker's storage under one prefix and writes the ids; teardown-cloudflare.mjs removes exactly that | your laptop | | docs/ | DEPLOY · ENV · CONTRACTS · INVENTORY · PARITY · DRIFT · DECISIONS · PROVISIONED · VERCEL_TEMPLATE | — |

Devices — what plugs in, and how

The production account behind this template runs a small fleet: Macs and a Linux box on the CLI (tiny-tech in production — shipped here as apps/cli, npx tiny-vercel), an iPhone and iPad, a WiFi Pineapple, a DJI drone, a Nicla Vision necklace, three e-ink Stickies, a robot arm and a 3D printer. They all reach the backend through app/api/devices/* in one of two ways:

| | Dial-in (kind: cli / daemon / browser) | Dial-out (kind: endpoint) | |---|---|---| | Who holds the credential | the device: a tind_… token in its config | the worker: a bearer it presents to the device | | Traffic | device heartbeats every 30 s, polls a relay mailbox, PATCHes replies; works behind NAT and on batteries | the worker calls GET /api/telemetry, POST /api/chat, GET /api/camera/snapshot on the device's public HTTPS URL | | Typical hardware | laptops (npx tiny-vercel), phones, ESP32 e-ink, MicroPython boards, OpenWrt routers | anything that already has a web API: a robot arm, a printer, a home server behind a tunnel | | Enroll | CLI consent flow: browser approves, code returns on 127.0.0.1, exchanged for a token — or POST /api/devices/adopt from a pairing screen | POST /api/devices {kind:"endpoint", url, secret} | | Try it | npx tiny-vercel init https://<your-app> && npx tiny-vercel login | examples/echo-device — 90 lines, three commands |

Pointing an existing client at your deployment is one setting: tiny-vercel init <url> (or TINY_API_URL) for the CLI, the api field in a Sticky's or Nicla's device config. The wire protocol they share is packages/contracts (docs/CONTRACTS.md); if you build a new device, implement the endpoint contract first — it needs no token on the device and the echo example is the whole spec.

Not included: the iOS and Android apps. They are clients of this API, like the CLI, and stay in their own repositories; they also currently pin tiny.technology as their origin, so a self-hosted backend is reached from the web UI and from devices, not from the phone apps. The web app is installable as a PWA and carries Web Push, so notifications and the Devices page work on a phone without them.

Quick start (local)

git clone https://github.com/cagataycali/tiny-vercel tiny-vercel && cd tiny-vercel
npm ci
cp .env.example apps/web/.env.local          # fill the "required" block — docs/ENV.md explains each variable
npm run dev:worker                            # http://127.0.0.1:8787 — Miniflare, local D1/KV/Vectorize
npm run dev:web                               # http://localhost:3000

For a real deployment follow docs/DEPLOY.md: one script provisions Cloudflare, one wrangler deploy, one click on the button above.

CLI — npx tiny-vercel

The CLI is in the repository (apps/cli) and is the same program the production fleet runs, with every tiny.technology constant replaced by one setting:

npx tiny-vercel init https://<your-app>.vercel.app   # probes /api/health, learns the worker, writes ~/.tiny/config.json
npx tiny-vercel login                                # browser consent → 90-day token; enrolls this machine as a device
npx tiny-vercel                                      # TUI in a terminal · MCP server when an MCP client spawns it
npx tiny-vercel mesh                                 # daemon: heartbeat, relay (use_device from the web agent), LAN mesh
claude mcp add tiny -- npx -y tiny-vercel            # your tiny's memory, DMs, jobs and tools inside Claude Code

Precedence: --api <url> → TINY_API_URL → ~/.tiny/config.json → the origin of an earlier login → an interactive prompt. Everything else (worker origin, site name) is read from the app's /api/health. From a checkout: npm ci --prefix apps/cli && node apps/cli/dist/cli.js …. Inventory and the 54 removed constants: docs/CLI.md; live proof against the demo: docs/EVIDENCE.md.

Development

npm ci && npm ci --prefix apps/cli              # the CLI keeps its own lockfile (React 19 vs the web's React 18 — docs/DECISIONS.md D-012)
npm run typecheck && npm run lint && npm test   # every workspace + the CLI's 1445 tests; CI runs the same plus a gitleaks scan
npm run build -w @tiny-vercel/web

Nothing in this repository points at tiny.technology: hosts, ids, keys and owner identity are environment variables (docs/ENV.md), and an unset value is an off switch, never a silent fallback. Where the original's docs and code disagreed, the code won and the difference is written down in docs/DRIFT.md.

The GitHub repository slug is still tiny-vercel; the project's name is tiny-vercel and package names use the @tiny-vercel/* scope.

License

Apache-2.0 — see LICENSE and NOTICE.