How-to guides
Step-by-step guides by use case - build, store files, add AI, secure and govern, ship and hand over - each ending in a passing mainsdk check.
Each guide solves one use case from start to finish: what you need, the steps, how to verify, what to do if it fails, and a prompt for your coding agent. Pick the row that matches what you want to do.
I want to
| Use case | Guide | Interfaces |
|---|---|---|
| Check whether an interface covers my need | What is covered | all |
| Build a SaaS, an AI chat, a marketplace or a wallet app | Stack recipes | auth, db, ai, pay, files |
| Move an app off raw provider SDKs | Migrate from raw providers | all |
| Move an app off Supabase, Firebase, Clerk, Auth0, Auth.js, Better Auth or Stripe | Migrate from Supabase, Firebase, Clerk, Auth0, Auth.js, Better Auth, Stripe | auth, db, pay |
| Start from a tested, production-shaped app | SaaS web, API service, Payments checkout, AI agent | all |
| Use MainSDK in a monorepo | Monorepos | config |
| Translate my app | Translate your app | i18n |
| Let users upload files to S3, Uploadthing, Vercel Blob or getqr.id | Upload files | files |
| Share a record, file or screen as a link and QR code, print QR codes, or send invite, deep and sign-in links | Share anything | share, links |
| Turn an email or a file into typed data, with a pattern first and a model only when it misses | Extract structured data | schema, ai |
| Add wallet sign-in, token gates or agent payments | Web3 and agent payments | auth, access, pay |
| Give an app agent a budget and approvals | Govern app agents | ai, action |
| Allow only certain hosts, IPs and ranges | Restrict network access | network |
| Declare the hosts, folders, facts and programs my app uses | Declare what your app uses | network, disk, system |
| See every call, decision and change, in my own tools | See what your app does | log, policy |
| Give enterprise customers SSO, SCIM and an audit log | Make your app enterprise ready | auth, access, log, privacy |
| Change a setting or roll out a feature without a deploy | Change config without a deploy | config, flags |
| Create a project, add an interface and check my machine | Start a project | config, log |
| Give each customer a tenant, API keys, plans and invites | Build a multi-tenant app | tenant, auth, apikeys, entitlements |
| Decide who can do what, and refuse the rest | Protect a route with permissions | access |
| Keep policy files in git and explain every decision | Keep policies in git | policy |
| Call a model with limits and audit | Call a model | ai |
| Take a payment on a hosted checkout | Take a payment | pay |
| Expose an action as an endpoint and an MCP tool | Expose an action to agents | action |
| Give an agent a budget and approvals in a few lines | Give an agent a budget | agents |
| Let an agent remember each customer and forget them on request | Give an app agent memory | memory, ai, agents |
| Roll a feature out to some users | Roll out with flags | flags |
| Deploy to Vercel | Deploy on Vercel | config, secrets |
| Use MainSDK from Rust | Use MainSDK from Rust | kv, files, log |
| Use MainSDK from Python | Use MainSDK from Python | db, files, log |
| Use MainSDK from Go | Use MainSDK from Go | db, files, log |
| Test offline with fakes | Testing | testing |
| Find out why something failed | Debugging | log |
| Change provider without changing code | Swap a driver | all |
| Leave MainSDK and keep my code | Eject | all |
| Hand a finished app to a client | Client handover | all |
| Invite a team, sign in with my identity provider and understand the bill | Set up a team on Teams | all |
| Call my typed API from React components | Call your API from React | api |
| Try a policy on a request and see what a change would flip | Try a policy in the playground | policy |
| Publish my actions as a typed API and OpenAPI document | Publish your actions as a typed API | api |
| Follow, block and mute, with a home timeline that ends and trending per region | Build a feed with an end | feeds |
| Import a customer's spreadsheet, then pull from a partner on a schedule | Import a customer's spreadsheet | imports, files |
| Let an agent act in a customer's Gmail or GitHub, with consent | Let an agent act in a customer's account | connections |
| Seed demo data and give each git branch a preview database | Seed demo data and make previews | testing, db |
| Track product events without identifying people | Track product events | analytics |
| Send reminders that bring people back, within limits | Send engagement reminders | engagement, notify |
| Send a receipt, a newsletter with unsubscribe and an order update on the channel a person allows | Send email and notifications | email, notify |
| Make, read and convert PDFs and Office documents | Make, read and convert documents | documents, pdf, files |
| Add health probes, SLOs and resource limits | Watch your app's health and resource pressure | status |
| Find out about errors before users do, grouped and alerted | Know when your app breaks | log, alerts |
| Page the right person once, with routes, grouping and acknowledgement | Tell the right person once with alerts | alerts |
| Stop a route, an agent or all writes during an incident, without a deploy | Switch things off in an incident | incident |
| Record consent, export a person's data and erase it with a signed record | Honour consent, export and erasure requests | privacy |
| Sign people in from a web page | Add sign-in to a page | adapters, auth |
| Run CPU-heavy work off the request thread | Run CPU work on workers | workers |
| Use every core for HTTP | Run one instance per core | cluster |
| Limit, meter and gate by plan | Limits, metering and entitlements | limits, meter, entitlements |
| Sell my app with signed licence files that switch features on, checked offline | License your app | licence, entitlements |
| Issue licences from MainSDK Cloud, with a root, a CA and a second approver | Issue licences from the Cloud | licence-cloud |
| Sign in to the Cloud, send events, read usage and set a billing cap | Use MainSDK Cloud | usage-billing |
| Add delete with undo, safe edits and non-blocking migrations | Change your database safely | db |
| Keep a draft or count events with an expiry | Keep short-lived values | kv |
| Make pages fast without sharing one customer's data | Cache safely | cache |
| Run work in the background with retries | Run work in the background | jobs, events |
| Verify incoming webhooks and send your own | Send and receive webhooks | webhooks, jobs |
| Sleep, wait and ask for approval in one function | Build a durable workflow | workflows, events, agents |
| Show untrusted text safely and send secure headers | Show untrusted text safely and protect web responses | sanitize, inbound |
| Protect a file so only the right people open it | Protect a file so only the right people open it | protect, share |
| Share a person's settings or progress between your apps, with consent | Share context between your apps | context |
| Use behaviour norms in your app | Use behaviour norms | norms |
| Check a release's checksums, signatures, provenance and SBOM before you install it | Verify a release | release |
| Subscribe to network, access and action events, assert on them in a test, and print them while you debug | Watch what your app decides | observe |
| Move an existing app onto MainSDK one pull request at a time | Adopt an existing app | adopt |
| Resize uploaded images and transcode video in a background job | Process uploaded images and video | media, files |
| Search your records as the person searching | Add search to your app | search |
| Run a GPU job with a cost limit and keep the result in files | Run a GPU job | compute, files |
| Find where your app fails a standard, see owners and deadlines, and keep signed evidence | Check your app against a standard | assure |
| Take reports, decide with a statement of reasons and export the transparency report | Moderate user content | moderate |
| Detect brute force and probing and send security events to your SIEM | Watch for security events | security |
| Give a coding agent the docs, types, next action and fixes | Work with a coding agent | mcp, docs |
| Rotate a secret without a restart | Rotate a secret | secrets |
| Catch made-up, vulnerable and badly licensed packages before they ship | Check your dependencies | deps |
| Sign my build, serve its record and check the files at boot | Seal your build | deploy, apps |
| Move my app to a new MainSDK release and learn about security releases | Upgrade MainSDK | upgrade |
| Respond to an attack or CPU pressure | Respond to an attack or CPU pressure | signals, playbooks |
| Link two apps on one machine and ask a neighbour for relief | Link two apps on one machine | apps, neighbours |
| Let a coding agent ask my running app about its state, with every change waiting for me | Operate your app with a coding agent | ops, playbooks |
| Give my customers API keys with scopes, rotation and instant revoke | Give my customers API keys with scopes, rotation and instant revoke | apikeys |
| Block paid features and limits by plan | Block paid features and limits by plan | entitlements |
| Record and show what each tenant uses | Record and show what each tenant uses | meter |
| Seal data and erase one person everywhere | Seal data and erase one person everywhere | keys, crypto |
| Send a link that opens the right screen | Send a link that opens the right screen | links |
| Require sign-in on my routes | Require sign-in on my routes | auth |
| Run a user's or an agent's code safely | Run a user's or an agent's code safely | sandbox |
| Read what Fleet pushed and prove it to an auditor | Read your Fleet records | fleet-prove |
| Emit and react to signals from my app | Emit and react to signals from my app | signals |
| Share a person's settings between your apps, with their consent | Share context between your apps | context |
| Share attack and pressure signals between apps on one machine | Share attack and pressure signals between apps on one machine | neighbours |
| Mount MainSDK in Next.js, Hono, Express or Workers | Mount MainSDK in Next.js, Hono, Express or Workers | adapters |
| Use tcp and udp sockets in your app | Use tcp and udp sockets | net |
| Enrol my devices, see their health and receive their telemetry | Enrol and watch your devices | device-identity, device-attest, device-health, device-telemetry |
| Send commands and policy to my devices | Command and configure your devices | device-commands, device-policy |
| See every app I run and what is exposed | See every app you run | fleet-enrolment, fleet-discover, fleet-observe |
| Use deploy config and serverless schedules in your app | Use deploy config and serverless schedules | deploy |
| Use offline-first replication in your app | Use offline-first replication | sync |
| Use realtime updates in your app | Use realtime updates | realtime |
| Use exfiltration guard and canaries in your app | Use exfiltration guard and canaries | canary |
| Use bot defence in your app | Use bot defence | bots |
| Use backups and restore drills in your app | Use backups and restore drills | backup |
| Build a mobile app with Expo | Build a mobile app with Expo | targets, notify |
| Sign in on a phone | Sign in on a phone | auth |
| Ask for an age or an ID | Ask for an age or an ID | digital-ids |
| Prepare for post-quantum and FIPS | Prepare for post-quantum and FIPS | crypto |
| Run on Workers, Deno and Bun | Run on Workers, Deno and Bun | targets |
| Keep your keys in an HSM or in your customer's own key service | Keep your keys in an HSM or in your customer's own key service | keys |
| Keep personal data in the person's own country | Keep personal data in the person's own country | keys |
| Confirm sensitive actions with a signed approval | Confirm sensitive actions with a signed approval | action |
| Add an industry pack to your app | Add an industry pack to your app | privacy |
| Publish a driver to the marketplace | Publish a driver to the marketplace | adapters |
| Send assure results to your GRC, vulnerability and ticket tools | Connect your security and ticket tools | connectors |
| Add calendars with recurrence and free/busy | Use calendars in your app | calendar |
| Receive a support inbox and thread replies | Receive and thread email | mail |
| Generate a video as a durable job | Generate a video | ai, files |
| Answer phone calls with an AI agent | Build a voice agent | ai, agents, privacy |
| Let a model propose a playbook for a person to approve | Propose playbooks with the advisor | advisor, playbooks |
| Use end-to-end encryption in your app | Use end-to-end encryption | e2e |
| Use phone, email and identity checks in your app | Use phone, email and identity checks | verify |
| Use location in your app | Use location | geo |
| Use app updates and version blocking in your app | Use app updates and version blocking | updates |
Interface reference pages say what each call does. Integration pages set up one provider. Architecture pages explain how it works inside. These guides join them into a result.
Was this page helpful?