Example apps

Four complete, runnable examples. Each demonstrates a different frontend stack and a different set of white-label capabilities. Clone the repo and follow the “Run locally” steps below each entry.

All examples live in examples/ at the root of the MIOSA GitHub repository.

whitelabel-saas

Stack: Python (Flask) backend + plain HTML/JS frontend

What it demonstrates:

• One-time tenant setup: custom preview domain, branding, webhook registration
• Per-customer sandbox provisioning with external_user_id, external_project_id, and metadata
• Server-side preview token minting and iframe embed
• HMAC-SHA256 webhook signature verification
• Teardown by external_user_id (cancellation flow)

This is the canonical reference example. Every concept in the white-label walkthrough maps directly to code in this example.

Run locally:

cd examples/whitelabel-saas
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env — fill in MIOSA_API_KEY

python setup.py      # one-time tenant setup
python app.py        # server on http://localhost:8000
# Open index.html in a browser for the embed demo

GitHub: examples/whitelabel-saas

whitelabel-react-saas

Stack: React 18 (Vite) frontend + Express.js BFF

What it demonstrates:

• BFF pattern: Express mints browser tokens; React uses @miosa/sdk directly in the browser
• Live terminal inside an iframe powered by the TypeScript SDK
• Per-user sandbox state stored in the BFF session
• Sandbox resume on page refresh (poll for state === "running" before showing the embed)
• Token refresh on miosa:preview:expired message event

Run locally:

cd examples/whitelabel-react-saas
pnpm install

cp .env.example .env
# Edit .env — fill in MIOSA_API_KEY

pnpm dev   # starts both Express (port 3001) and Vite (port 5173)
# Open http://localhost:5173

GitHub: examples/whitelabel-react-saas

whitelabel-nextjs-marketplace

Stack: Next.js 15 (App Router) full-stack

What it demonstrates:

• Next.js Route Handlers as the BFF: token minting without a separate Express server
• Seller onboarding: sandbox provisioned on first login, re-used on return
• Multi-project listing: sandboxes filtered by external_user_id and rendered as cards
• Usage display: per-seller compute hours fetched with client.usage.get(external_user_id)
• Custom next.config.js to proxy sandbox previews through the Next.js server (avoid CORS for embedded iframes)

Run locally:

cd examples/whitelabel-nextjs-marketplace
pnpm install

cp .env.local.example .env.local
# Edit .env.local — fill in MIOSA_API_KEY

pnpm dev   # starts on http://localhost:3000

GitHub: examples/whitelabel-nextjs-marketplace

whitelabel-vue-tutor

Stack: Vue 3 (Vite) frontend + Express.js backend

What it demonstrates:

• Per-lesson sandbox lifecycle: fresh sandbox per lesson, destroyed on completion
• Quota enforcement: custom middleware rejects sandbox.create if the user has reached their limit
• Public share links with a 15-minute TTL for peer review
• File-tree component: reads the sandbox filesystem via client.files.list(sandboxId, "/")
• Run-button component: streams exec output via client.exec.stream(sandboxId, "npm test")

Run locally:

cd examples/whitelabel-vue-tutor
pnpm install

cp .env.example .env
# Edit .env — fill in MIOSA_API_KEY

pnpm dev   # starts both Express (port 3001) and Vite (port 5174)
# Open http://localhost:5174

GitHub: examples/whitelabel-vue-tutor

Feature matrix

Contributing an example

If you build something on MIOSA and want to share it, open a pull request in the MIOSA GitHub repository. Examples must:

• Include a working README.md with local setup instructions
• Not commit MIOSA_API_KEY or any secrets
• Use external_user_id for all resource attribution
• Verify webhook signatures if a webhook endpoint is included

See also

• End-to-end walkthrough
• Preview Tokens
• Webhooks reference