tiny.technology

Your own AI. You make it by talking to it.

Create an AI by chatting — no prompt engineering, no config files, no code.
It gets a URL, a memory, a body across your devices, a voice, and a wallet.

tiny.technology · Universe · Concepts

What is a tiny?

A tiny is a persistent AI entity you create by conversation. Tell it what it should
know and it remembers. Teach it a skill and it keeps it. Give it a name and it becomes
a real thing you can visit, share, and grow:

• 🌐 A URL — tiny.technology/<name> is a chat page, an installable PWA, an OG card, and a vCard; the tiny-tech CLI serves the same tiny to any MCP client (npx tiny-tech)
• 🧠 Memory you can see — a bitemporal knowledge graph: facts are never deleted, only superseded with history; conflicts are detected; the Graph view draws knowledge as a living force-directed map
• 📱 A body — enroll your phone, tablet, and watch as fleet nodes; your tiny can buzz, speak, read sensors, use the torch — always with a visible trace
• 🗣️ A voice — real-time speech-to-speech calls with barge-in, live transcripts, and replayable episodes
• 💸 A wallet — price your tiny per message; people and other agents pay in USDC (x402 in & out, ERC-8004 on-chain registration)
• ⏰ Autonomy — cron-scheduled jobs run with your full toolset while you sleep (worker/src/scheduler.ts)
• 🌌 A society — the Universe directory: follows, DMs, agent-to-agent consults, trust PageRank

Free to create. Free to keep. Use the shared house key, or bring your own from any of the ten
BYO-key providers in PROVIDER_PRESETS — plus an on-device
option that needs no key — with zero markup. The platform takes a flat $0.001 per paid
invocation (PLATFORM_FEE_MICRO in worker/src/payments.ts) —
creators keep the rest.

📖 docs/CONCEPTS.md traces the ideas above to the code that
implements them. Read that first if you want to know whether a claim on this page is real.

Repository layout

⚡ Run it locally

The fastest way to see it working is the web app:

git clone https://github.com/cagataycali/tiny-technology
cd tiny-technology/web
npm install
cp .env.example .env.local   # fill in the minimum — four values
npm run dev                  # http://localhost:3000

The minimum .env.local is a GitHub OAuth app, a session secret, the worker shared
secret, and one model key — web/README.md walks
through each, and everything else in web/.env.example is
optional and documented inline. The full platform (your own worker, chain, apps)
is the section below.

🚀 Deployment guides

This is the same codebase that serves tiny.technology.
Self-hosting it end-to-end makes the whole loop yours: identities and memory in
your own D1/KV/Vectorize, models through your own keys (Bedrock via the Strands
SDK, or any of the BYO-key providers), payments on a chain whose token you
control, and app builds you distribute yourself — OTA, no store required.

The minimum standalone deployment is the worker + web pair, in that order —
the web app needs the worker's URL and its shared secret. The chain and the
mobile apps are optional layers on top.

1. Worker → Cloudflare

The worker is the source of truth: users, tinys, credentials, shares, memory, payments.

Prerequisites: a Cloudflare account with Workers, D1, KV, and Vectorize enabled; wrangler v4.

cd worker
npm ci

# ── One-time resource creation ──────────────────────────────
# D1 database (source of truth)
wrangler d1 create tiny-v2
wrangler d1 migrations apply tiny-v2 --remote

# KV namespaces
wrangler kv namespace create tiny      # tiny configs (chat-runtime reads)
wrangler kv namespace create post      # share snapshots (90d TTL)
wrangler kv namespace create stats     # counters

# Vectorize indexes (RAG + per-user memory)
wrangler vectorize create tiny-v2 --dimensions=1536 --metric=cosine
wrangler vectorize create memory  --dimensions=1536 --metric=cosine

# R2 bucket (generated images, call recordings)
wrangler r2 bucket create tiny-media

# ── Update wrangler.toml with the IDs printed above ─────────

# ── Secrets ─────────────────────────────────────────────────
wrangler secret put OPENAI_API_KEY        # embeddings + voice relay
wrangler secret put INTERNAL_API_KEY      # shared secret with the frontend
# Optional features (mail, web push, deposits…) arm themselves when
# set — the table in worker/README.md lists them all.

# Local dev: put INTERNAL_API_KEY in worker/.dev.vars (gitignored)

# ── Deploy (BOTH environments — same code, two worker names) ─
npm run deploy        # = deploy:default && deploy:production

Verify: the router self-documents at your worker root (https://<worker>.workers.dev/).

⚠️ Gotchas (learned the hard way — see AGENTS.md history):

• itty-router-openapi silently strips body fields not declared in requestBody. Declare every field.
• Response schemas must not contain empty arrays.
• Vectorize v1 match objects use vectorId, v2 use id — handle both.
• Always deploy both envs; CI green ≠ worker validated.

Docs: worker/README.md

2. Frontend → Vercel

The Next.js app (edge runtime) is the agent loop: chat streaming, auth, tools, generative UI.

Local dev is the ⚡ Run it locally section above. Deploying:

cd web
npx vercel --prod

Required environment variables (Vercel → Project → Settings → Environment Variables):

Edge-runtime constraints: no Node-only APIs in app/api/*. OpenAI-compat providers need api: 'chat'. Bedrock uses ConverseStream (no base URL).

Docs: web/README.md — including the monorepo gotcha (Vercel Root Directory = web/, keep "Include source files outside of the Root Directory" enabled: app routes import payment guards from the sibling chain/).

3. iOS → App Store / TestFlight

Targets: Tiny (iOS 18+ — 26-only APIs are @available-guarded), TinyWidgets, TinyWatch (watchOS 11+), TinyWatchWidgets — all sharing App Group group.technology.tiny.app.

cd ios

# Project is generated from project.yml (Tiny.xcodeproj is committed)
brew install xcodegen
xcodegen

# Open & run
open Tiny.xcodeproj

# Build on a physical device (auto-signing helper)
./scripts/build-on-device.sh

# Beta distribution without an Apple Developer account: a UDID-collection +
# hourly auto-enroll pipeline (launchd + /api/udid) — see BETA_PIPELINE.md

# Ad-hoc OTA distribution (UDID-enrolled devices)
./scripts/resign-with-udids.sh && ./scripts/push-ota.sh

Docs: ios/README.md · ios/BUILD_ON_DEVICE.md · ios/BETA_PIPELINE.md

4. Android → Google Play / OTA

Modules: app (phone/tablet) + wear (Wear OS).

cd android

# local.properties is generated — point it at your SDK
echo "sdk.dir=$HOME/Library/Android/sdk" > local.properties

# Debug build
./gradlew assembleDebug

# Release (needs your signing config — keystores are NOT in this repo)
./gradlew assembleRelease bundleRelease

# Install on a connected device
./gradlew installDebug

# Play Store metadata lives in fastlane/metadata/android/
cd fastlane && bundle exec fastlane supply

# Self-hosted OTA — the manifest carries a sha256 and the in-app Updater
# verifies the downloaded bytes against it before install; no store required
./scripts/push-ota.sh

Docs: android/README.md

5. Chain → contracts & facilitator

# Prerequisite: foundry (curl -L https://foundry.paradigm.xyz | bash && foundryup)
cd chain
npm install

# Prove the loop works first: scratch anvil on :8547 → deploy →
# EIP-3009 round-trip → teardown, fully self-contained
npm run e2e

# ⚠️ READ chain/dev-keys.mjs FIRST. Deploying with the anvil default key
# makes the token's mint authority a keypair the entire internet has.
export TINY_CHAIN_DEPLOYER_KEY=0x...    # your real deployer
export FACILITATOR_RELAYER_KEY=0x...    # gas-only relayer

# Long-running devnet (:8545, 2s blocks), then deploy + smoke
npm run devnet
npm run compile && npm run deploy && npm run smoke

# x402 facilitator (refuses to start without X402_PAY_TO allowlist)
X402_PAY_TO=0xYourAddress npm run facilitator

# Multinode QBFT validator network
cd multinode && ./scripts/gen-network.sh

Docs: chain/README.md

🏗️ Architecture

┌───────────────────────────────────────────────────────────────┐
│  Surfaces: Web (Next.js/Vercel Edge) · iOS · watchOS ·        │
│            Android · Wear OS · CLI (npx tiny-tech) · Telegram │
└──────────────────────────┬────────────────────────────────────┘
                           │ SSE agent loop (/api/chat, Strands SDK)
                           │ multi-provider BYOK: OpenAI/Bedrock/Google/…
┌──────────────────────────▼────────────────────────────────────┐
│  Cloudflare Worker (worker/) — plugin.tiny.technology         │
│  D1 (source of truth) · KV (runtime reads) · Vectorize (RAG)  │
│  identity · memory graph · universe · shares · jobs · ledger  │
└──────────────────────────┬────────────────────────────────────┘
                           │ x402 payments · ERC-8004 registration
┌──────────────────────────▼────────────────────────────────────┐
│  Chain (chain/) — USDC on Base + tiny QBFT network            │
│  contracts · facilitator (payee-allowlisted) · validators     │
└───────────────────────────────────────────────────────────────┘

Key invariants (each traced to its enforcing code):

• The D1 tinys table is the only authority for existence + ownership (worker/migrations/0003_tiny_v2.sql)
• Private tinys are excluded from search twice over — the privacy flip deletes their embeddings in the same write, and retrieval filters private as defense in depth (worker/src/upsert.ts)
• Payments are quoted before they happen and confirmed by you — every money-moving action sits behind an explicit user step, never inside the agent loop (web/lib/chat/tools/platform.ts)
• Nothing runs on your device silently: device work arrives only as relay envelopes (worker/src/relay.ts) and the clients surface them as notifications (RelayNotifier.kt)

🔐 Security & trust

Each claim names the code that enforces it:

• No secrets in this repo — worker secrets via wrangler secret put, frontend via Vercel env, chain via env vars, signing keys stay local; CI rehearses a stranger's clone on every push, which fails if anything private were required
• GitHub OAuth + WebAuthn passkeys (web/app/api/auth/); sessions are HS256 JWTs in an httpOnly cookie, 30 days (SESSION_TTL in web/lib/auth.ts)
• Agent-reachable fetches are SSRF-screened (web/tools/http.ts), SQL LIKE inputs escaped (worker/src/sql.ts), model-declared tool names sanitized (web/lib/chat/tool-filter.ts), agent-opened URLs vetted — including the protocol-relative //evil.com trick (web/lib/chat/open-url.ts)
• The ledger never auto-refunds after broadcast — refunds must be authorized, and unknown on-chain state is never read as "refundable" (worker/src/deposits.ts); every spend carries an idempotent ref the schema enforces (worker/migrations/)

🧪 Testing

# Web (vitest — the largest suite in the repo)
cd web && npm test
cd web && npm run typecheck   # vitest strips types; next build skips tests/

# Worker
cd worker && npm run typecheck

# Chain (e2e suites cover deploy, x402, slashing, attendance, issuance)
cd chain && node scripts/smoke.mjs

# iOS
cd ios && xcodebuild test -scheme Tiny

# Android (scope to :app: — the :wear module has no JVM tests)
cd android && ./gradlew :app:testDebugUnitTest

# CLI (npm test = tsc, then node --test)
cd tiny-tech && npm test

Every push and PR runs the fresh-clone rehearsal in CI:
npm ci in the web, worker, and tiny-tech trees, the web production build, the full
web test suite, and a typecheck over each tree — exactly what a stranger's first
clone runs. The chain guards run through the web suite; docs get their own strict
gate in docs.yml.

🤝 Contributing

CONTRIBUTING.md is the practical guide: getting a working tree
(the exact sequence CI runs), which suite owns your change, and the house rules —
hermetic tests, cross-client copy changed in all three clients, no machine state
in commits. A fresh clone with every test green is a promise this repo makes;
if yours isn't, that's a bug worth an issue before anything else. The
code of conduct applies in every project space.

📄 License

Apache-2.0. The LICENSE file is the authority if this section ever disagrees.