Platform builder guide

MIOSA gives you machines, previews, and deployments. A platform is what you build on top of them so that other people can use them without ever learning how they work.

This guide is for builders of products like Lovable, Devin, or agent platforms. In these products, your product makes a sandbox for each of your own users.

Such a platform needs:

A sandbox per user or project: Patterns.
A private preview URL of what the user builds: Branding and domain setup.
An agent or harness working inside the machine: Agents in your product.
Deployments and Docker Host: Deploy overview.
White-label, tenants, scoped tokens, and external users: Branding and domain setup and Ownership and attribution.
Billing and caps: Templates and sizing.

Choose a shape

Every platform on MIOSA uses one model. Three shapes cover most products.

You are	Example	Who uses it	What is white-labeled
A SaaS shipping an agent product	Lumen	Lumen’s customers	Everything: domains, branding, billing
An agency running client work	Northwind Agency	Northwind’s clients	Client previews and delivery domains
A company with a team	Acme Corp	Acme’s own staff and agents	Nothing. It is internal

If you only need the internal case, jump to Acme Corp: an internal platform.

Northwind Agency: client work

The full architectures - Lumen, Northwind Agency client work, and Acme Corp - are walked in Patterns.

1. Create a scoped platform key

Platform keys (msk_p_*) are for server-side automation. Only tenant owners and administrators can create them. Give each key only the scopes the backend needs, and optionally restrict it to one workspace.

The plaintext is returned exactly once and MIOSA stores only a hash. Rotation, scopes, and audit are covered in API keys.

2. Create a workspace per customer

Do this once, when the customer signs up, and store the returned IDs next to your own row.

You can also skip this step. If a create call carries workspace_slug or external_workspace_id and the workspace does not exist, MIOSA resolves or creates it. The response returns the canonical workspace_id and project_id, so store those and reuse them. Details in Ownership and attribution.

3. Give each user a machine

One sandbox or computer per end user, never shared across customers.

Each machine has its own filesystem, network, and process tree. Sizing, templates, and idle defaults are in Templates and sizing.

Pick what you need

You want to	Page
Provision one sandbox per end user	Patterns
Run an agent inside your users’ machines	Agents in your product
Pick sizes, templates, and idle defaults	Templates and sizing
Put your brand on previews and apps	Branding and domain setup
Attribute resources and usage to your customers	Ownership and attribution
Meter usage and charge back	Usage and billing

The three architectures that cover most products, and how to provision each one.

Give each user a machine with an agent or harness working inside it.

Connect a customer’s Claude or ChatGPT plan, or their model key, from your own code.

Sizes, costs, templates, quotas, and idle defaults.

The internal-company version of this guide.

API keys Key families, scopes, rotation, and audit.

Ownership and attribution Workspace and project ownership plus your external IDs.

Branding and domain setup Preview domains, deployment domains, custom domains, and branding.

Browser tokens Short-lived tokens for previews and terminals in the end user's browser.

Connect agent accounts Keys and subscription plans, for your workspace or per end user.

Usage and billing Per-customer usage and chargeback on a single MIOSA bill.

Build gallery Step-by-step guides for 20+ product shapes.

Reference integration

Runnable examples live in examples/. See examples/agent-builds-static-app/ for the “agent builds, previews, and deploys” pattern.