# MainSDK facts: the single machine-readable source of truth about MainSDK. # # Who reads it: tools/build_docs.py (llms.txt intro, JSON-LD, FAQPage on the docs home), # the landing page (designs/site/index.html FAQ and JSON-LD are kept word for word in sync # with the entries marked on_landing), and anyone writing about MainSDK. # # Rules # - Every statement here is true today or is labelled with the phase or milestone it ships in. # MainSDK is pre-release: nothing is published yet. Say so wherever status matters. # - Every section names its source in this repository. If a source changes, change this file # in the same PR. # - No prices on public pages (owner). Say that MainSDK Cloud has plans; never quote them. # - No "first", "only", "world's" or other superlatives. Drafts of those live in # docs/brand/claims.md with approved: false and are not published until the owner approves. # - Voice: designs/03-brand/voice.md. Sentence case, short and concrete, "we" for MainSDK, # "you" for the developer, no hype words. version: 1 updated: 2026-10-26 name: MainSDK alternate_names: [mainsdk, Main SDK] pronunciation: "main S-D-K" package: mainsdk # npm, not yet published (docs/requirements/mainsdk-requirements.md#getting-started-and-technical-specifications) cli: mainsdk tagline: "Agents build. You ship safe and reliable." secondary_line: "Main stays green." definition: # The canonical one-sentence definition. Quote it verbatim. sentence: >- MainSDK is the open-source app runtime for apps built by AI coding agents: standard interfaces with swappable drivers, one main.yaml manifest, and checks that keep agent-written code safe, reliable and compliant by default. description_50: >- MainSDK is the open-source app runtime for apps built by AI coding agents. One TypeScript SDK gives an app sign-in, access, data, AI, payments and more behind standard interfaces with swappable drivers. main.yaml declares the app, and mainsdk check verifies every change before it ships. In-app capabilities are free under Apache-2.0. description_150: >- MainSDK is the open-source app runtime for apps built by AI coding agents. Like Android or iOS for a phone app, it gives every web and API app the building blocks it should not rebuild: sign-in, permissions, data, AI calls, payments, email, files, jobs, secrets and logs, 40 interfaces in all. Your code calls one standard interface per capability, and a driver connects it to the provider you choose in one main.yaml file, so switching providers changes a line, not your code. The mainsdk check command runs on your laptop and in CI and fails a change that leaks a key, skips a permission or calls an undeclared host, then hands the fix back to your coding agent. Everything that runs inside your app is free and open source under Apache-2.0; MainSDK Cloud adds paid plans for teams and companies. MainSDK is made by HubXero. It is pre-release: the TypeScript public beta is milestone 0.5. source: - README.md - docs/brief.md - docs/requirements/mainsdk-requirements.md#overview - docs/requirements/mainsdk-requirements.md#an-app-runtime-like-android-and-ios - docs/catalog/interfaces.yaml # 40 interfaces category: primary: App runtime SDK schema_org: applicationCategory: DeveloperApplication applicationSubCategory: App runtime SDK also_described_as: - code-safe SDK ("type-safe stops bad types; code-safe stops bad apps") - capability layer with swappable drivers source: docs/requirements/mainsdk-requirements.md#positioning what_it_is: items: - An SDK (the npm package mainsdk), a CLI and an MCP server that live in your repository. - A standard interface per capability (40 in the catalog), each with drivers for the providers you already use. - One manifest, main.yaml, that declares what the app is, needs and may do. - A check, mainsdk check, that runs locally and in CI before a change reaches main. - Pure TypeScript with zero runtime dependencies, and no native binary to install. source: - docs/requirements/mainsdk-requirements.md#overview - docs/adr/0066-typescript-is-the-core-until-phase-5-and-the-rust-core-arrives-with-python-and-go.md - docs/adr/0075-each-language-sdk-is-its-own-native-library-sharing-contracts-and-data-never-code.md what_it_is_not: items: - Not a new framework to learn. It runs inside Next.js, Hono, Express and Node workers. - Not a hosting platform. You deploy wherever you deploy today. - Not a no-code builder. - Not a scanner that hands you a list of findings. Failures go back to the agent with the fix. - Not lock-in. Every provider sits behind a contract you can swap, and eject writes plain provider code. - Not a sidecar, daemon or extra service. It is imported like any other library. source: - docs/requirements/mainsdk-requirements.md#positioning - docs/adr/0001-typescript-first-on-a-rust-core.md - docs/adr/0066-typescript-is-the-core-until-phase-5-and-the-rust-core-arrives-with-python-and-go.md - docs/adr/0075-each-language-sdk-is-its-own-native-library-sharing-contracts-and-data-never-code.md audience: items: - who: Builders detail: Founders, operators, domain experts and product managers with little or no coding background, building with Claude Code, Cursor, Lovable or Replit. outcome: "I shipped, and it's safe." - who: Freelancers, agencies and software shops detail: Rescue and ship client apps fast, and prove the work with a report the client can read. outcome: Find, fix and prove in one afternoon. - who: Teams who build together detail: Shared policy, PR checks, traces and debugging across the team's projects. outcome: See how the app runs, trace it, debug it and ship it reliably together. - who: Enterprise security and platform teams detail: CTOs, CISOs and platform leaders who want many teams building with agents under one standard. outcome: "Every team ships fast, and we can prove every app meets our standard." source: - docs/requirements/mainsdk-requirements.md#who-its-for - docs/requirements/mainsdk-requirements.md#positioning problems: # The six pains on the landing page, ranked. Evidence is quoted as the sources state it. intro: Agents reach a working demo fast. What breaks is everything a demo never tests. items: - id: p1 title: Keys in the frontend pain: API keys shipped to the browser; bills maxed out overnight and paywalls bypassed. evidence: AI-assisted commits leak secrets at about twice the human rate. source_name: GitGuardian source_urls: ["https://blog.logrocket.com/vibe-coding-failures/", "https://www.arnica.io/blog/vibe-coding-security-risks"] how_mainsdk_helps: Interfaces take secret references only, and a key in code fails the check. - id: p2 title: Every user reads every record pain: Row-level security off; users' data readable without login. evidence: One flaw, CVE-2025-48757, left about 170 AI-built apps open. source_name: CVE-2025-48757 source_urls: ["https://www.cve.org/CVERecord?id=CVE-2025-48757"] how_mainsdk_helps: Every action checks permissions, deny by default, and data is scoped to its owner. - id: p3 title: The agent deletes production pain: Production data deleted during a code freeze, with no undo. evidence: In July 2025 an agent wiped about 1,206 executive records during a code freeze. source_name: Public reports of the July 2025 Replit incident source_urls: ["https://www.vybe.build/blog/vibe-coding-mistakes"] how_mainsdk_helps: Destructive actions wait for a signed human approval. - id: p4 title: Packages that don't exist pain: Agents install hallucinated packages, and a look-alike package ships malware. evidence: 19.7% of sampled agent code named a nonexistent package. source_name: Cloud Security Alliance source_urls: [] how_mainsdk_helps: Every dependency is verified before install. - id: p5 title: Diffs nobody can read pain: Changes too big to review are approved unread, and old flows break. evidence: Lines per pull request rose about 250% in a year. source_name: Cursor (2026) source_urls: [] how_mainsdk_helps: The check reports what behaviour changed, not how many lines. - id: p6 title: The enterprise deal stalls pain: No SSO, audit log or security evidence, so months of building before you can sell. evidence: Every enterprise buyer asks for SSO, audit logs and a security review. source_name: MainSDK requirements (Problems we solve) source_urls: [] how_mainsdk_helps: SAML, SCIM and audit export are in the SDK, free. source: - designs/01-research/pains.json - docs/requirements/mainsdk-requirements.md#problems-we-solve note: >- The "57% of reachable Supabase databases" figure in the requirements is a secondary source the requirements say must be reproduced before it is quoted publicly. Do not use it. how_it_works: items: - step: 1 name: Install text: npx mainsdk init finds your framework, writes main.yaml and tells your coding agent the rules. - step: 2 name: Declare text: Name a driver for each capability in main.yaml, such as GitHub for sign-in, Amazon Bedrock for AI and Postgres for data. One line each. - step: 3 name: Check and ship text: mainsdk check runs the same checks on your laptop and in CI. A change ships only when it passes, and failures go back to the agent with the fix. source: - designs/site/index.md - docs/requirements/mainsdk-requirements.md#getting-started-and-technical-specifications key_features: - name: Standard interfaces with swappable drivers text: 40 interfaces, from auth and db to ai, pay and email. Switching a provider is one line of main.yaml. source: docs/catalog/interfaces.yaml - name: One manifest text: main.yaml declares the app's drivers, permissions, allowed hosts and data labels, with overlays per market, segment or environment. source: docs/site/concepts/main-yaml.md - name: The check text: mainsdk check fails a key in code, an action without a permission or a call to an undeclared host, in observe, warn or enforce mode, with SARIF for CI. source: docs/site/concepts/the-check.md - name: Every action is also a tool text: Write an action once and get an API endpoint, a server action, a CLI command and an opt-in MCP tool, all behind one policy. source: docs/specs/mcp-actions.md - name: Policy as code text: Cedar built in by default, OPA as a driver, ReBAC engines such as OpenFGA and SpiceDB through access. Policies live in git and roll out in shadow first. source: docs/adr/0004-cedar-default-policy-engine.md - name: Never in the request path text: Policy decisions run in process; no user request waits on MainSDK Cloud, and the app keeps its last good policy if the Cloud is unreachable. source: docs/adr/0003-never-in-the-request-path.md - name: Data by region text: Each record is stored in its owner's region (US, EU or India), and the check refuses joins across regions. source: docs/adr/0006-data-stored-by-region.md - name: Passkeys by default text: Phishing-resistant sign-in by default; admin roles must use passkeys or SSO with phishing-resistant MFA. source: docs/adr/0008-passkeys-by-default.md - name: Private AI calls text: Keys out of code, personal data redacted before the model sees it, providers that train on or keep prompts refused, spend limits per user and feature. source: docs/catalog/interfaces.yaml#ai - name: Enterprise features for your customers, free text: SAML and OIDC SSO, SCIM, audit log export and customer-managed keys inside the SDK. source: docs/site/guides/enterprise-ready.md - name: Main 27 text: The named, versioned minimum every MainSDK app meets, modern methods only; the Main mark is the signed proof a release holds it. source: docs/requirements/mainsdk-requirements.md#spec-main-27-and-the-main-mark - name: Signed delivery text: Packs and driver metadata are delivered through The Update Framework (TUF); releases are signed. source: docs/adr/0005-tuf-for-everything-delivered.md - name: Eject text: mainsdk eject writes plain provider code in place of MainSDK calls, for one interface or all of them, and keeps your tests. Recipes are proposed for email, pay, auth and db first. source: docs/specs/eject.md - name: Testing kit text: In-memory fakes of every interface, time control and injected provider outages, with no provider account. source: docs/specs/testing-kit.md technical: language: TypeScript (ESM) runtime: Node.js 22 or later core: Pure TypeScript, zero runtime dependencies; Rust, Python and Go get their own native SDKs in phase 5, sharing contracts and data, never code operating_systems: [macOS, Linux, Windows] package_managers: [npm, pnpm, bun] # bun as a package manager; the Bun runtime is phase 5 agents: Any MCP-capable coding agent, including Claude Code, Cursor, Codex and GitHub Copilot performance_budgets: policy_decision: under 1 ms at p99 added_per_request: under 2 ms browser_bundle: under 150 KB cold_start: under 20 ms source: - docs/requirements/mainsdk-requirements.md#getting-started-and-technical-specifications - docs/adr/0066-typescript-is-the-core-until-phase-5-and-the-rust-core-arrives-with-python-and-go.md - docs/adr/0075-each-language-sdk-is-its-own-native-library-sharing-contracts-and-data-never-code.md - docs/adr/0003-never-in-the-request-path.md - docs/site/getting-started/installation.md frameworks: supported_first: # adapters planned for milestone 0.2 - Next.js (App Router: route handlers, server actions, proxy) - Hono - Express - Node workers data_layers: [Prisma, Drizzle] later: - { name: Expo and React Native, phase: 3 } - { name: Bun, Deno and Cloudflare Workers runtimes, phase: 5 } - { name: Native Rust SDK (first), then Python and Go SDKs, phase: 5 } source: - docs/specs/adapters.md - docs/requirements/mainsdk-requirements.md#roadmap-five-phases drivers_by_capability: # Generated from docs/catalog/interfaces.yaml (2026-10-26). Regenerate when the catalog changes. # Every interface is status: planned. Logos and names belong to their owners. source: docs/catalog/interfaces.yaml capabilities: - capability: Identity interfaces: - { id: auth, name: "Sign-in and sessions", drivers: ["GitHub", "Clerk", "Auth0", "Better Auth", "WorkOS", "Supabase Auth", "Local (development only)"] } - { id: verify, name: "Phone, email and identity checks", drivers: ["Bird", "Twilio Verify", "DigiLocker", "Onfido", "Persona"] } - capability: Access interfaces: - { id: access, name: "Permissions", drivers: ["Cedar (built in)", "Open Policy Agent", "OpenFGA", "SpiceDB", "Cerbos", "Permit.io", "Oso", "AWS Verified Permissions"] } - { id: policy, name: "Policy decisions", drivers: ["Cedar (built in)", "Open Policy Agent"] } - capability: Data interfaces: - { id: db, name: "Data and records", drivers: ["Postgres", "Neon", "Supabase", "SQLite (local only)"] } - { id: kv, name: "Key-value store and cache", drivers: ["Upstash Redis", "Redis", "Vercel Runtime Cache", "Cloudflare KV"] } - { id: search, name: "Search and vector search", drivers: ["Typesense", "Meilisearch", "Algolia", "pgvector"] } - capability: AI interfaces: - { id: ai, name: "AI calls", drivers: ["Amazon Bedrock", "Anthropic", "OpenAI", "AI gateway", "Local fake"] } - { id: action, name: "Actions and agent tools", drivers: ["MCP", "HTTP API", "Server actions", "CLI"] } - capability: Payments interfaces: - { id: pay, name: "Payments", drivers: ["Stripe", "Razorpay", "Paddle", "Local test cards"] } - { id: meter, name: "Usage metering", drivers: ["Stripe meters", "Lago"] } - capability: Messaging interfaces: - { id: notify, name: "Notifications", drivers: ["WhatsApp Cloud API", "Bird", "MSG91", "Twilio", "Local terminal channel", "Firebase Cloud Messaging", "Apple Push Notification service", "Expo", "Resend", "Amazon SES", "OneSignal"] } - { id: email, name: "Email", drivers: ["Resend", "Amazon SES", "Local inbox", "Postmark", "Bird", "SMTP"] } - { id: realtime, name: "Realtime updates", drivers: ["Pusher", "Ably", "Supabase Realtime"] } - capability: Files and links interfaces: - { id: files, name: "File uploads", drivers: ["getqr.id", "Amazon S3 and S3-compatible stores", "Uploadthing", "Vercel Blob", "Local files on disk"] } - { id: share, name: "Share links and QR codes", drivers: ["getqr.id"] } - { id: links, name: "App links", drivers: ["getqr.id"] } - { id: media, name: "Images and video", drivers: ["getqr.id", "Cloudinary", "Mux"] } - { id: pdf, name: "PDF documents", drivers: ["Built in", "DocRaptor", "Documenso"] } - capability: Events and jobs interfaces: - { id: webhooks, name: "Webhooks", drivers: ["Built in", "Svix"] } - { id: jobs, name: "Events and background jobs", drivers: ["Inngest", "Vercel Queues", "In-process local queue", "Trigger.dev", "Amazon SQS"] } - capability: Security interfaces: - { id: secrets, name: "Secrets", drivers: ["HashiCorp Vault", "AWS Secrets Manager", "Google Secret Manager", "Azure Key Vault", "Doppler", "Infisical", "Environment variables", "Local file"] } - { id: keys, name: "Encryption keys", drivers: ["AWS KMS", "Google Cloud KMS", "Azure Key Vault", "Vault Transit", "Local (development only)"] } - { id: crypto, name: "Cryptography", drivers: ["Cloud key services", "Vault Transit", "libsodium"] } - { id: network, name: "Network permissions", drivers: ["Built in"] } - { id: limits, name: "Rate limits and quotas", drivers: ["Built in", "Upstash", "Arcjet"] } - { id: protect, name: "Protected files", drivers: ["Self-hosted TAPS Node", "Hosted TAPS Node", "SoveDocs"] } - capability: Privacy interfaces: - { id: privacy, name: "Privacy and data rights", drivers: ["Built in"] } - capability: Reliability interfaces: - { id: backup, name: "Backups and restore drills", drivers: ["Neon point-in-time recovery", "Supabase point-in-time recovery", "pgBackRest", "AWS Backup", "Object storage with object lock"] } - { id: status, name: "Health and status page", drivers: ["Built in", "Your status page provider"] } - capability: Observability interfaces: - { id: log, name: "Logs, audit and telemetry", drivers: ["Terminal", "Any OpenTelemetry backend", "MainSDK Cloud"] } - { id: analytics, name: "Product analytics", drivers: ["PostHog", "Plausible", "Google Analytics", "Segment", "MainSDK Cloud"] } - { id: stats, name: "Where the app is used", drivers: ["Built in"] } - capability: Experience interfaces: - { id: i18n, name: "Languages and formats", drivers: ["Local YAML files", "Tolgee", "Crowdin", "Lokalise", "AI draft with human review"] } - { id: geo, name: "Location", drivers: ["Platform headers", "Mapbox", "Google Maps Platform"] } - { id: updates, name: "App updates and version blocking", drivers: ["Expo Updates", "App Store", "Google Play", "Tauri updater"] } - { id: feedback, name: "Feedback and support", drivers: ["Built in", "Intercom", "Zendesk", "Plain"] } - capability: Platform interfaces: - { id: config, name: "Runtime settings", drivers: ["Files", "Vercel Global Config", "AWS AppConfig", "Cloudflare KV"] } - { id: flags, name: "Feature flags", drivers: ["Any OpenFeature provider", "PostHog", "Vercel Flags"] } - { id: testing, name: "Testing kit", drivers: ["In-memory fakes"] } anything_else: Build a driver with the driver kit, or call the provider directly through raw(). licence: spdx: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 scope: >- Everything that runs inside an app: the SDK and its TypeScript core, the CLI, every check, gate and guarantee, every driver, the MCP server and the policy engine. contributions: DCO sign-off source: - docs/adr/0007-apache-2-and-in-app-free.md - docs/requirements/mainsdk-requirements.md#product-principles price: in_app: Free, forever. An app protecting itself is never a paid feature. cloud: >- MainSDK Cloud offers plans for one developer, for teams and for companies. They charge only for what the Cloud runs: hosted history, team workflow and company-wide governance. public_prices: none # owner: no prices on public pages; plan details are shown after sign-in schema_org_offer: { price: "0", priceCurrency: USD } # the in-app SDK source: - docs/adr/0007-apache-2-and-in-app-free.md - docs/requirements/mainsdk-requirements.md#packaging-and-pricing-proposed maker: name: HubXero description: A lab that generates tomorrow's ideas and executes them. slogan: innovation begins github: https://github.com/hubxero endorsement: A HubXero product related_products: - { name: GetQR ID, url: https://getqr.id, role: "Sharing, uploads and QR codes for MainSDK's files, share and links interfaces" } source: - README.md - docs/adr/0009-sharing-through-getqr-id.md urls: home: https://mainsdk.dev/ docs: https://mainsdk.dev/docs docs_search: https://mainsdk.dev/docs?q={search_term_string} llms_txt: https://mainsdk.dev/llms.txt llms_full_txt: https://mainsdk.dev/llms-full.txt facts: https://mainsdk.dev/facts.yaml # proposed public copy of this file; see docs/brand/integration.md github: https://github.com/hubxero/mainsdk # the public repository named on the landing; not created yet security_policy: https://mainsdk.dev/security security_txt: https://mainsdk.dev/.well-known/security.txt status_page: https://status.mainsdk.dev/ og_image_home: https://mainsdk.dev/og/home.png og_image_docs: https://mainsdk.dev/og/docs.png status: stage: pre-release summary: >- MainSDK is pre-release. It is in design, no package is published, and the docs describe the planned product. The TypeScript public beta is milestone 0.5; version 1.0 follows an independent audit. current_as_of: 2026-10-26 milestones: - { id: "0.1", name: Foundation, phase: 1, ships: "Repo, CI and signed builds, contract toolchain, main.yaml schema" } - { id: "0.2", name: Core loop, phase: 1, ships: "init, sync, check and local mode; config, secrets, policy and log; Next.js, Hono and Express adapters" } - { id: "0.3", name: Every interface, phase: 1, ships: "The phase 1 stable core interfaces with two drivers each and passing conformance" } - { id: "0.4", name: Hardening, phase: 1, ships: "TUF delivery, fail-static proven, performance budgets in CI, threat models, testing kit, Main 27" } - { id: "0.5", name: Pilot ready, phase: 1, ships: "Public beta: docs, migration skill, community open" } - { id: "0.6", name: Cloud, phase: 2, ships: "MainSDK Cloud in US, EU and India; console; debug loop" } - { id: "1.0", name: General availability, phase: 2, ships: "Independent audit published, contracts frozen for 1.x, long-term support line" } phases: - { phase: 1, name: "Core, public beta" } - { phase: 2, name: "Cloud and Teams, 1.0" } - { phase: 3, name: "Mobile and regulated industries" } - { phase: 4, name: "Fleet" } - { phase: 5, name: "Every language" } source: - docs/specs/README.md - docs/requirements/mainsdk-requirements.md#roadmap-five-phases comparisons: # Fair framing. Describe the difference in approach; never run another product down. - vs: Writing auth, payments and email by hand (or asking the agent to) summary: >- An agent can write a SAML integration or a payment flow, but it cannot promise the code is correct, kept up to date and ready for a security review. With MainSDK the agent writes one interface call, such as auth.sso.enable() or pay.checkout(), and MainSDK supplies the work behind it: metadata exchange, certificate rotation, verified webhooks and audit logs. source: docs/requirements/mainsdk-requirements.md#already-built-the-hard-parts - vs: Security scanners summary: >- Scanners find problems after the code exists and are deep at it. MainSDK works earlier: the safeguards are inside the building blocks the agent uses, the check verifies rules, intent and outcomes before main, and policy is enforced at runtime. MainSDK bundles open-source scanners rather than competing on rule counts, and runs alongside the scanner you have. source: docs/requirements/mainsdk-requirements.md#competition-and-differentiation - vs: Provider and platform SDKs (for example Stripe, Clerk, Supabase, Resend) summary: >- Provider SDKs give you one provider's API, and they are good at it. MainSDK uses them as drivers behind a standard interface, so your code makes the same call whichever provider you pick, and gains policy checks, audit logs, redaction and region rules. Providers are partners, not competitors, and raw() reaches any provider feature MainSDK does not cover. source: docs/requirements/mainsdk-requirements.md#competition-and-differentiation - vs: App builders (for example Lovable, Bolt, v0, Replit) summary: >- Builders are where many apps are made, and MainSDK works with all of them in your own repository. Bring an app over with mainsdk check and the migration skill, one pull request at a time. source: docs/requirements/mainsdk-requirements.md#competition-and-differentiation - vs: Web frameworks (for example Next.js, Hono, Express) summary: >- MainSDK is not a framework. It runs inside the framework you use, through an adapter, and adds the capabilities and checks around your code. source: docs/specs/adapters.md faqs: items: # 40 to 80 words per answer, self-contained, first sentence a direct answer. # on_landing: true means designs/site/index.html shows it, and its visible text and FAQPage # JSON-LD must match this file word for word. - id: what-is on_landing: true q: What is MainSDK? a: >- MainSDK is the open-source app runtime for apps built by AI coding agents. Your app calls standard interfaces for sign-in, access, data, AI, payments and more, and a driver connects each one to the provider you choose in one main.yaml file. The mainsdk check command verifies every change before it ships. MainSDK is made by HubXero and is free under Apache-2.0. - id: who-for q: Who is MainSDK for? a: >- MainSDK is for people who ship apps with AI coding agents. That includes founders and builders with little coding background, freelancers and agencies who rescue and ship client apps, teams who build together, and security and platform teams who govern many apps. Builders start free, and teams and companies pay only for what MainSDK Cloud runs for them. - id: free on_landing: true q: Is MainSDK free? a: >- Yes. Everything that runs inside your app is free and open source under Apache-2.0: the SDK, the CLI, every check and guarantee, every driver, the MCP server and the policy engine. MainSDK Cloud has paid plans for hosted history, team workflow and company-wide governance. An app protecting itself is never a paid feature. - id: open-source q: Is MainSDK open source? a: >- Yes. MainSDK is licensed under Apache-2.0, and everything that runs inside your app is open source: the TypeScript SDK and core, the CLI, the checks, the drivers, the MCP server and the policy engine. Contributions carry a DCO sign-off. MainSDK Cloud, the hosted service for teams and companies, is where the paid plans apply. - id: production-ready on_landing: true q: Is MainSDK production-ready? a: >- No, not yet. MainSDK is pre-release: it is in design, and no package is published. Work runs in milestones from 0.1 Foundation to 0.5 Pilot ready, which is the public beta of the TypeScript SDK. Version 1.0 follows an independent audit. Until then, read the docs as the planned design and watch the GitHub repository for releases. - id: how-it-works q: How does MainSDK work? a: >- MainSDK works in three steps. First, npx mainsdk init finds your framework, writes main.yaml and tells your coding agent the rules. Second, you name a driver for each capability, such as GitHub for sign-in or Amazon Bedrock for AI, one line each. Third, mainsdk check runs the same checks on your laptop and in CI, and a change ships only when it passes. - id: vs-scanner on_landing: true q: How is MainSDK different from a security scanner? a: >- A scanner reports problems after the code exists; MainSDK puts the safeguards inside the building blocks your agent uses. Keys stay out of code because interfaces take secret references, and every action checks permissions by default. The check then verifies rules, intent and outcomes before a change reaches main, and sends failures back to the agent with the fix. MainSDK bundles open-source scanners and runs alongside yours. - id: nextjs on_landing: true q: Does MainSDK work with Next.js? a: >- Yes. Next.js is a first target, with an App Router adapter that covers route handlers, server actions and the proxy. Hono, Express and Node workers have adapters too, and Prisma or Drizzle plug in as the data layer. You need TypeScript and Node.js 22 or later. The adapters are planned for milestone 0.2, before the public beta. - id: frameworks q: Which frameworks and runtimes does MainSDK support? a: >- MainSDK targets TypeScript on Node.js 22 or later, with adapters for Next.js, Hono, Express and Node workers, and Prisma or Drizzle for data. An Expo and React Native adapter for mobile follows in phase 3. Bun, Deno and Cloudflare Workers as runtimes, and native Rust, Python and Go SDKs, follow in phase 5. - id: ai-providers on_landing: true q: Which AI providers does MainSDK support? a: >- The ai interface has drivers for Amazon Bedrock, Anthropic and OpenAI, plus an AI gateway driver and a local fake for tests. You pick one in main.yaml and can switch later without changing code. Every call keeps provider keys out of code, redacts personal data before the model sees it, refuses providers that train on or keep prompts, and enforces spend limits per user. - id: coding-agents on_landing: true q: Which AI coding agents work with MainSDK? a: >- Any agent that speaks the Model Context Protocol (MCP) works with MainSDK, including Claude Code, Cursor, Codex and GitHub Copilot. mainsdk init writes AGENTS.md rules for your agent, and the MCP server exposes your app's actions as tools. Apps started in Lovable, Bolt, v0 or Replit come over through mainsdk check and the migration skill. - id: existing-app on_landing: true q: Can I use MainSDK on an app I already built? a: >- Yes. Run mainsdk check on an existing TypeScript app to see what to fix, then use mainsdk adopt and the migration skill to move it onto MainSDK one pull request at a time, with no rewrite. This is the intended first step for apps built with Lovable, Bolt, v0 or Cursor, and the goal is a useful result in under five minutes. - id: main-yaml q: What is main.yaml? a: >- main.yaml is the one file that declares what a MainSDK app is, needs and may do, like a mobile app's manifest. It names the driver for each interface, the hosts the app may call, its data labels and its permissions. Overlays such as main.in.yaml hold what differs by market, segment or environment, and the most specific file wins. - id: check q: What does mainsdk check do? a: >- mainsdk check verifies an app before it ships, on your laptop and in CI. It fails on problems such as a key in code, an action without a permission or a call to an undeclared host, and explains the fix. It runs in observe, warn or enforce mode and writes SARIF for CI. Every check is free and runs on your own machine. - id: switch-providers on_landing: true q: Can I switch providers without rewriting code? a: >- Yes. Your code calls an interface such as pay or email, and the provider is one line in main.yaml. Moving from Stripe to Razorpay, or from Amazon Bedrock to Anthropic, changes that line, not your code. Shadow mode for the new driver and a guided job that moves stored state are planned and not specified yet. Anything not covered can call the provider directly through raw(). - id: lock-in q: Does MainSDK lock me in? a: >- No. Every provider sits behind a contract you can swap, everything inside your app is Apache-2.0, and mainsdk eject leaves MainSDK for one interface or all of them. Eject writes plain provider code in place of MainSDK calls and keeps your tests, so leaving is a supported path, not a rewrite. - id: cloud-down on_landing: true q: Does my app go down if MainSDK Cloud goes down? a: >- No. MainSDK is designed never to sit in the request path: policy decisions run inside your app, no user request waits on MainSDK Cloud, and telemetry never blocks. If the Cloud is slow or unreachable, your app keeps its last good policy, packs and config and keeps serving. Plan limits affect only the Cloud, never your running app. - id: data-regions q: Where does MainSDK store data? a: >- Data is stored by region: US, EU and India. The db interface keeps one store per region and writes each record to its owner's region, and mainsdk check refuses queries that join across regions. MainSDK Cloud runs in the same three regions. Personal data is labelled in the schema, so one call can export or erase a person everywhere. - id: framework-or-host q: Is MainSDK a framework or a hosting platform? a: >- Neither. MainSDK is a library, a CLI and an MCP server that live in your repository and run inside the framework you already use, such as Next.js, Hono or Express. You deploy wherever you deploy today. It is not a no-code builder either, and it needs no sidecar or extra service: you import it like any other package. - id: vs-provider-sdks q: How is MainSDK different from using provider SDKs directly? a: >- Provider SDKs such as Stripe's or Clerk's give you one provider's API; MainSDK uses them as drivers behind a standard interface. Your code makes the same call whichever provider you pick, plus what MainSDK adds around it: policy checks, audit logs, redaction, verified webhooks and region rules. Providers are partners, and raw() reaches any provider feature MainSDK does not cover. - id: vs-by-hand q: Why not ask my coding agent to write auth and payments itself? a: >- Because an agent can write a SAML integration or a payment flow, but it cannot promise the code is correct, kept up to date and ready for a security review. With MainSDK the agent writes one interface call, such as auth.sso.enable() or pay.checkout(), and MainSDK supplies the work behind it: metadata exchange, certificate rotation, verified webhooks and audit logs. - id: main27 q: What is Main 27? a: >- Main 27 is the named, versioned minimum every MainSDK app meets: modern methods only, such as passkeys, TLS 1.3 and Argon2id, with older methods retired rather than supported. It is named for the year it serves, like Wi-Fi 6, and Main 28 follows in autumn 2027. The Main mark is the signed proof that a release holds it. - id: maker q: Who makes MainSDK? a: >- MainSDK is made by HubXero, a lab that generates tomorrow's ideas and executes them. HubXero builds a family of products that share capabilities: MainSDK's sharing, uploads and QR codes go through GetQR ID, another HubXero product. MainSDK is built in the open under Apache-2.0, with a public repository, RFCs and roadmap planned for phase 1. - id: languages q: Does MainSDK support Rust, Python or Go? a: >- Not yet. MainSDK ships TypeScript only through phase 4, on Node.js 22 or later. In phase 5 a native Rust SDK comes first, for apps, services and endpoint agents, then Python and Go. Each is its own idiomatic library with the same interfaces, main.yaml, error codes and checks as TypeScript. They share contracts and test data, not code: no shared core, no FFI and no sidecar. Rust may arrive sooner if the owner decides. source: - docs/requirements/mainsdk-requirements.md - docs/adr/ - docs/catalog/interfaces.yaml - docs/specs/adapters.md - docs/site/getting-started/existing-app.md - docs/site/guides/swap-a-driver.md - docs/site/guides/eject.md