---
title: "How-to guides"
description: "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."
section: "guides"
canonical: "https://mainsdk.dev/docs/guides/index"
updated: "2026-10-28"
---

# 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.

Canonical: https://mainsdk.dev/docs/guides/index · Updated: 2026-10-28

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