# somewhere.cloud — platform overview and topic index For a first live app, follow the [anonymous quickstart](https://somewhere.cloud/docs/start.txt). It needs no account and gives the builder a temporary app to claim. > **What this file is:** a short OVERVIEW of the whole platform, then the > COMPLETE TOPIC INDEX. It is not the API manual. Every topic is its own > plain-text page, `https://somewhere.cloud/docs/.txt`, and needs no CLI, MCP or account to read. > The complete manual is [docs.txt](https://somewhere.cloud/docs.txt) (also > [llms-full.txt](https://somewhere.cloud/llms-full.txt)); it is large, so fetch the > topic you need. The index ends with a line starting `END OF TOPIC INDEX` that > states how many topics it lists. If you cannot see that line, your copy was cut > off: fetch topic pages directly. ## How Somewhere works Somewhere is in public beta. Somewhere is the backend for apps your agent builds. One project gives your app its web address, server functions, one SQL database, sign-in, files, email, AI and background work. Write React and TypeScript, then run `somewhere deploy`. The platform compiles your source and serves the app and its functions together. A starter has these parts: | Part | Source | Purpose | |---|---|---| | App | `src/`, `index.html` | The interface and browser routes. | | Functions | `api/` | Server code: `api/notes.ts` answers `/api/notes`. Every handler receives `sw`, bound to the project. | | Data | `db/schema.ts` | Optional: tables, columns and access rules, applied on deploy. The default starter has none. | | Auth | `api/auth/[...path].ts`, `src/auth/` | Working sign-in and session hooks to extend. | The default starter includes sign-in; minimal and bare starters omit it. Browser sessions use Secure, HttpOnly cookies. Normal owner-table operations get the user from the verified session and scope rows to that user. A table's `client` block chooses which operations and columns the browser may use. Your functions decide who may perform privileged actions. Check the caller before using server authority, sending an email or charging a card. Keep secrets in `sw.env`, read them inside handlers, and make repeated effects safe with a stable operation identity. Deploy raw source from the app root; the platform handles compilation. Expose a browser value only with `public: true` and a `VITE_` or `REACT_APP_` name; visitors can read it. Start with [Start an app](https://somewhere.cloud/docs/getting-started.txt), [Data](https://somewhere.cloud/docs/declared-data.txt), [Auth](https://somewhere.cloud/docs/sw.auth.txt), [Functions](https://somewhere.cloud/docs/functions.txt) and [Env vars and secrets](https://somewhere.cloud/docs/sw.env.txt). Each primitive opens with one working path and links to deeper sections. Recipes contain complete jobs and live outside this short reading path. The index below lists every topic, including specialized capabilities. Use `somewhere docs ` or MCP `docs({ topic })`. To load one section, use `somewhere docs --section ` or `docs({ topic, section })`. Use an explicit full view for the complete reference. Recipe first calls already return the whole recipe. ## Other references - [Ordered working guide](https://somewhere.cloud/build.txt) · [Guides and recipes](https://somewhere.cloud/guides.txt) - [Agent contract for initialized projects](https://somewhere.cloud/agent.txt) · [Migration and portability](https://somewhere.cloud/migration.txt) · [Browse topics](https://somewhere.cloud/docs) - Coding agents with a shell can also use `somewhere docs `; MCP clients (endpoint `https://mcp.somewhere.cloud/mcp`) can use `docs({ topic })`. ## Complete topic index ### How Somewhere works - [Handled for you — the foundation behind your app](https://somewhere.cloud/docs/handled-for-you.txt) — Built-in work and the choices your app owns. - [Database — SQL support, capabilities, and limits](https://somewhere.cloud/docs/database-engine.txt) — Capabilities, limits, concurrency, supported SQL. - [Security model — who can read/write what](https://somewhere.cloud/docs/security-model.txt) — Developer, project, end-user, and server authority boundaries. - [Built-in protections — what the platform handles](https://somewhere.cloud/docs/guarantees.txt) — Runtime, deploy and safety responsibilities. - [Portability — getting your data out](https://somewhere.cloud/docs/portability.txt) — Export data and move your app. ### Primitives - [Start an app](https://somewhere.cloud/docs/getting-started.txt) — Build, deploy, and verify a first app. - [Deployed Functions](https://somewhere.cloud/docs/functions.txt) — Server routes, HTML pages and SPA coexistence with Request/Response and sw. - [sw.env — Environment Variables (inside deployed functions)](https://somewhere.cloud/docs/sw.env.txt) — Server keys and deliberate public browser keys in one store. - [Declared data — the schema file is the contract](https://somewhere.cloud/docs/declared-data.txt) — Schema, access rules, typed client. - [Groups](https://somewhere.cloud/docs/sw.groups.txt) — Shared rows, invites and roles. - [sw.db — Database (inside deployed functions)](https://somewhere.cloud/docs/sw.db.txt) — Queries, atomic writes, live views and server SQL. - [Auth — End-User Authentication](https://somewhere.cloud/docs/sw.auth.txt) — Sign-in, sessions, OAuth and account settings. - [Files](https://somewhere.cloud/docs/declared-files.txt) — Who reads, uploads, replaces, deletes files; somewhere:files. - [sw.fs — File Storage (inside deployed functions)](https://somewhere.cloud/docs/sw.fs.txt) — Store, read, version, publish, sign, move, and upload files. - [Email](https://somewhere.cloud/docs/sw.email.txt) — Email on every plan: managed sender for users/owner; own sender domain for anyone. Caps: `/v1/pricing`. - [AI and search](https://somewhere.cloud/docs/sw.ai.txt) — Text, image, speech, embeddings, moderation, memory and agents. - [Search — managed document search and named indexes](https://somewhere.cloud/docs/search.txt) — Search files or build semantic indexes over app data. - [Somewhere agent loop — sw.agent](https://somewhere.cloud/docs/sw.agent.txt) — Bound agent steps and spend; hooks, durable status, retries. - [Jobs and schedules](https://somewhere.cloud/docs/sw.jobs.txt) — Background jobs: status, retries, cancel. - [Cron — Scheduled Tasks](https://somewhere.cloud/docs/cron.txt) — Schedule recurring function execution with cron expressions. - [Payments](https://somewhere.cloud/docs/payments.txt) — Onboard sellers; charge, refund, reconcile. - [Deploy and domains](https://somewhere.cloud/docs/deploy.txt) — Deploy source, promote, roll back and undeploy. - [Custom Domains](https://somewhere.cloud/docs/domains.txt) — Attach, verify, inspect, and remove custom domains. - [Test, observe and troubleshoot](https://somewhere.cloud/docs/browser.txt) — Test live pages, screenshots and interactions. - [sw.endpoint — declarative endpoint wrapper](https://somewhere.cloud/docs/sw.endpoint.txt) — Optional auth, validation and rate limiting around a handler. - [sw.fetch — outbound HTTP fetch from a function](https://somewhere.cloud/docs/sw.fetch.txt) — Policy-checked outbound HTTP requests from deployed functions. - [sw.rateLimit — Rate limiting](https://somewhere.cloud/docs/sw.rateLimit.txt) — Limit requests and actions. - [sw.notifications — unified notify primitive](https://somewhere.cloud/docs/sw.notifications.txt) — One notification through bell, push, or zero-setup email. - [sw.push — Web Push notifications](https://somewhere.cloud/docs/sw.push.txt) — Browser notifications; per-device send history. - [Inbox — Inbound Email](https://somewhere.cloud/docs/inbox.txt) — Receive, search, thread, reply to, and route inbound email. - [Live updates — a browser subscribing to a declared database view](https://somewhere.cloud/docs/live.txt) — Subscribe a browser to a declared live view. - [Project groups](https://somewhere.cloud/docs/project-groups.txt) — Organize projects with shared access and themes. - [Render — PDFs](https://somewhere.cloud/docs/render.txt) — Render HTML or URLs into PDF documents. - [sw.web — Read pages from the public web](https://somewhere.cloud/docs/sw.web.txt) — Read and extract content from public web pages. - [sw.image — Image transformations](https://somewhere.cloud/docs/sw.image.txt) — Transform, resize, convert, and optimize image assets. - [Calendar — atomic holds and reservations](https://somewhere.cloud/docs/calendar.txt) — Atomic time holds, availability, confirmation and release. - [sw.billing — plans & feature gating for YOUR app's users](https://somewhere.cloud/docs/sw.billing.txt) — Plans and entitlements for your app's own users. ### Recipes and jobs - [Recipe — Sign-in, email alerts, daily reminder](https://somewhere.cloud/docs/recipe-signed-in-app.txt) — Owner rows, contact form and daily reminder. - [Recipe — Sign-in: the starter, your data, then providers](https://somewhere.cloud/docs/recipe-login.txt) — Starter login, social sign-in and magic links. - [Recipe — File uploads: each user's own files](https://somewhere.cloud/docs/recipe-file-uploads.txt) — Owner-scoped uploads from the page. - [Recipe — Email the signed-in user](https://somewhere.cloud/docs/recipe-email.txt) — Verified recipients, test inbox, send outcomes. - [Recipe — Push notifications to a signed-in user](https://somewhere.cloud/docs/recipe-push-notifications.txt) — Notify a user; check delivery. - [Recipe — A background job with a status the user sees](https://somewhere.cloud/docs/recipe-background-jobs.txt) — Per-user work, status and repeat-safe results. - [Recipe — AI features: suggest a title](https://somewhere.cloud/docs/recipe-ai-features.txt) — Signed-in model call, model choice, AI options. - [Recipe — Read receipts with AI](https://somewhere.cloud/docs/recipe-ai-receipts.txt) — Read private receipts with AI; review and save. - [Recipe — SEO: titles, previews, sitemap](https://somewhere.cloud/docs/recipe-seo.txt) — Titles, link previews, sitemap, robots and SEO checks. - [Recipe — CSV import](https://somewhere.cloud/docs/recipe-csv-import.txt) — Upload, one job, retry-safe batched writes. - [Recipe — PDFs](https://somewhere.cloud/docs/recipe-pdfs.txt) — Generate, store privately, preview, merge, split. - [Recipe — Paid and OAuth-protected APIs](https://somewhere.cloud/docs/recipe-paid-api.txt) — 402 payment and 401 OAuth challenges. - [Recipe — Bring an existing app](https://somewhere.cloud/docs/recipe-import-app.txt) — From GitHub, a folder, a zip, Supabase or Lovable. - [Recipe — AI agent with tool calls](https://somewhere.cloud/docs/recipe-ai-agent.txt) — Agent chatbot with owner rows and conversation history. - [Recipe — Booking / calendar app](https://somewhere.cloud/docs/recipe-booking.txt) — Start booking checkout with a calendar hold. - [Recipe — Fixed-price catalog checkout](https://somewhere.cloud/docs/recipe-ecommerce.txt) — Start a fixed-price catalog checkout. - [Recipe — Multi-chat (Claude.ai-style conversation list)](https://somewhere.cloud/docs/recipe-multi-chat.txt) — Multi-conversation chat with history and search. - [Recipe — Cheap model escalates to smart model when stuck](https://somewhere.cloud/docs/recipe-escalation.txt) — A low-cost model escalates to a stronger one when stuck. - [Live data — one poller, fan out to every client](https://somewhere.cloud/docs/live-data.txt) — Recipe: one cron poller, fanned out by a live view. - [Architecture Patterns — How to wire common app shapes](https://somewhere.cloud/docs/architecture-patterns.txt) — Compose primitives into common app architectures. - [Migrating a Supabase app](https://somewhere.cloud/docs/migration-supabase.txt) — Move a Supabase app and its data. ### Surfaces - [Setup — Use the CLI, or connect MCP without a shell](https://somewhere.cloud/docs/setup.txt) — Connect with CLI or MCP. - [@somewhere-cloud/cli — full command reference](https://somewhere.cloud/docs/cli.txt) — CLI commands and JSON output. - [@somewhere-cloud/sdk — optional adapter, one auth path](https://somewhere.cloud/docs/sdk.txt) — Optional SDK for browser and server code. - [Client SDK — JavaScript and TypeScript](https://somewhere.cloud/docs/sdks.txt) — JS/TS SDK: starter auth, typed function calls, automation. - [Local dev — `somewhere dev`](https://somewhere.cloud/docs/local-dev.txt) — Run locally with `somewhere dev`; pull, typecheck, inspect. - [Auth on the client — the correct session code](https://somewhere.cloud/docs/auth-client.txt) — Browser sign-in with HttpOnly cookies. - [Typed functions — one contract, both sides](https://somewhere.cloud/docs/typed-functions.txt) — Typed handlers and browser calls. - [GitHub push-to-deploy](https://somewhere.cloud/docs/github.txt) — Deploy on GitHub push; check status. - [Preview — `somewhere preview` (every plan)](https://somewhere.cloud/docs/dev-environments.txt) — Private previews for signed-in accounts on every plan. - [Projects — Full Lifecycle](https://somewhere.cloud/docs/projects.txt) — Create, edit, export and manage projects. - [Inspect — Read live state before writing](https://somewhere.cloud/docs/inspect.txt) — Inspect source, releases, routes, logs and live state. ### Reference and help - [Verify before deploy](https://somewhere.cloud/docs/verify-before-deploy.txt) — Typecheck, compile and handler checks, and unit tests. - [Limits](https://somewhere.cloud/docs/limits.txt) — Function, record, env, upload, and deploy ceilings. - [Deploy intelligence — what a deploy records, and where to read it](https://somewhere.cloud/docs/deploy-intelligence.txt) — Analysis and diagnostics after each deploy. - [Smoke tests — deploy and recurring checks](https://somewhere.cloud/docs/smoke.txt) — Automatic uptime and behavior checks. - [SQL compatibility — what Postgres code ports, and what doesn't](https://somewhere.cloud/docs/sql-compatibility.txt) — How Postgres-style SQL translates and where it differs. - [PostgreSQL](https://somewhere.cloud/docs/postgres.txt) — Attach a PostgreSQL database you own; use its driver. - [CORS — which browser origins may call your project's functions](https://somewhere.cloud/docs/cors.txt) — Your own origins already work; add a third-party origin. - [Design System — Read before generating UI](https://somewhere.cloud/docs/design-system.txt) — Starter tokens, components, themes and design. - [Pricing](https://somewhere.cloud/docs/pricing.txt) — Current plans and limits. - [Plans & Pricing](https://somewhere.cloud/docs/billing.txt) — Usage, plan activation and account billing. - [Pricing comparison — somewhere.cloud vs the stack](https://somewhere.cloud/docs/pricing-comparison.txt) — Compare costs with a conventional assembled stack. - [You own your domain](https://somewhere.cloud/docs/domain-ownership.txt) — Domain custody, portability, renewal and detachment. - [sw.logs — Application Logging (inside deployed functions)](https://somewhere.cloud/docs/sw.logs.txt) — Write logs and inspect failures. - [Analytics — Track Events, Query Aggregates](https://somewhere.cloud/docs/analytics.txt) — Track events and query aggregates for an application. - [Tasks — shared context for work](https://somewhere.cloud/docs/tasks.txt) — Per-project work, comments, relationships, completion. - [Recent behaviour changes](https://somewhere.cloud/docs/changes.txt) — Dated behaviour changes. - [Platform Feedback — Bug? Doc gap? Tell us.](https://somewhere.cloud/docs/feedback.txt) — Report and follow platform or docs issues. - [Speed](https://somewhere.cloud/docs/speed.txt) — Measure latency and speed up your app. - [Common Mistakes — Things real users have hit](https://somewhere.cloud/docs/common-mistakes.txt) — Avoid recurring deploy, auth, database, and file mistakes. - [Troubleshooting — Common errors and what to do](https://somewhere.cloud/docs/troubleshooting.txt) — Common platform errors and their recovery paths. - [File tools — project-wide search, glob, diff and integrity check](https://somewhere.cloud/docs/file-tools.txt) — Developer search, glob, diff, integrity checks. - [Discovered API surface](https://somewhere.cloud/docs/api-surface.txt) — REST, runtime and MCP calls. - [somewhere.cloud vs Supabase — honest comparison](https://somewhere.cloud/docs/vs-supabase.txt) — Compare capabilities and operating tradeoffs with Supabase. - [somewhere.cloud vs Vercel — honest comparison](https://somewhere.cloud/docs/vs-vercel.txt) — Compare capabilities and operating tradeoffs with Vercel. END OF TOPIC INDEX — 93 topics listed above. Every topic is also its own page at https://somewhere.cloud/docs/.txt.