Build your own product on MIOSA
MIOSA gives you the full compute and preview infrastructure. You own the product, the brand, and the user relationship. Your customers never see “MIOSA”.
This section covers everything you need to ship a white-label SaaS on top of MIOSA: per-user provisioning, custom domains, secure iframe embeds, webhooks, usage metering, and abuse controls.
What white-label tenants get
| Capability | What it means for your product |
|---|---|
| Isolated sandboxes per user | Each customer project runs in its own microVM with its own filesystem, network, and process tree. |
| Custom preview domains | Sandbox previews serve from *.opendesigns.ai instead of *.miosa.app. |
| Short-lived preview tokens | Mint a server-side token, pass it to the browser - never expose your API key client-side. |
| Webhook lifecycle events | Receive sandbox.running, sandbox.destroyed, and more at your own HTTPS endpoint. |
| Usage rollup by user | Query compute usage keyed to your own external_user_id for per-seat billing. |
| Per-user quotas | Set max sandboxes, max CPU, or max runtime per user to prevent runaway spend. |
| Branded failure pages | 502 and 404 errors in previews show your logo, not MIOSA’s. |
| Full filesystem and terminal access | Expose a file tree, terminal, or run-button in your UI using the SDK - no shell into MIOSA required. |
Architecture patterns
Three deployment patterns cover the vast majority of integrations. All three keep your msk_* API key server-side.
Pattern 1 - Server-side proxy (recommended for most teams)
Your backend owns all MIOSA calls. The browser only receives a short-lived preview URL from your API. This is the simplest pattern and the one used in the whitelabel-saas example.
When to use: You already have a backend. You want the tightest control over what each user can do. No SDK needed in the browser.
Pattern 2 - Backend-for-Frontend (BFF)
A thin BFF layer authenticates the user, resolves their MIOSA workspace/project IDs, and returns a short-lived JWT. The browser then calls MIOSA directly using that token.
When to use: High-volume preview-heavy products where round-tripping every terminal keystroke through your backend adds latency.
Pattern 3 - Direct with browser tokens
Your backend mints a scoped browser token (mp_...) once. The browser uses @miosa/sdk directly with that token for file reads, exec calls, and preview embeds.
When to use: Interactive coding tools or IDEs where the browser needs low-latency direct access to the sandbox.
Five-minute path for new integrators
- One-time setup - register your domain, set branding, configure a webhook
- Provision a sandbox per user -
client.sandboxes.create(external_user_id=...) - Embed the preview - mint a token server-side, drop an
<iframe>in your UI - Handle lifecycle events - react to
sandbox.running,sandbox.destroyed - Bill by user - query usage keyed to your
external_user_id
Example apps
Four full-stack examples you can clone and run locally:
The canonical white-label walkthrough. OpenDesigns.ai - a design tool SaaS - provisions sandboxes per customer project, embeds previews in iframes, and verifies lifecycle webhooks.
A React frontend with an Express BFF. Shows how to mint browser tokens server-side and use the TypeScript SDK directly from the browser for live terminal access.
A Next.js App Router marketplace where each seller gets an isolated sandbox for their storefront. Uses Route Handlers for token minting and Server Components for usage display.
An interactive coding tutor. Each lesson runs in a fresh sandbox. Demonstrates quota enforcement, public share links, and the file-tree SDK primitives.