---
title: "Platform builder guide"
description: "Run your users' agents, previews, and workspaces on MIOSA: architectures, costs, and provisioning patterns."
last_updated: 2026-10-23
url: https://miosa.ai/docs/platform/overview
---

# 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](https://miosa.ai/docs/platform/patterns.md).
- A private preview URL of what the user builds: [Branding and domain setup](https://miosa.ai/docs/platform/white-label.md).
- An agent or harness working inside the machine: [Agents in your product](https://miosa.ai/docs/platform/agents-in-your-product.md).
- Deployments and Docker Host: [Deploy overview](https://miosa.ai/docs/docker-host/overview.md).
- White-label, tenants, scoped tokens, and external users: [Branding and domain setup](https://miosa.ai/docs/platform/white-label.md) and [Ownership and attribution](https://miosa.ai/docs/platform/attribution.md).
- Billing and caps: [Templates and sizing](https://miosa.ai/docs/platform/templates-and-sizing.md).

## 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](https://miosa.ai/docs/platform/patterns.md#acme-corp-an-internal-platform).

## Northwind Agency: client work

The full architectures - Lumen, Northwind Agency client work, and Acme Corp - are walked in [Patterns](https://miosa.ai/docs/platform/patterns.md).

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

**TypeScript**

```typescript
const key = await miosa.apiKeys.create({
  name: "Lumen backend prod",
  key_type: "platform",
  workspace_id: workspaceId,
  scopes: ["sandboxes:write", "deployments:write", "domains:write"],
})

console.log(key.key) // shown once, store it in your secret manager
```

**Python**

```python
from miosa import Miosa

miosa = Miosa(api_key="msk_u_...")

key = miosa.api_keys.create(
    name="Lumen backend prod",
    key_type="platform",
    workspace_id=workspace_id,
    scopes=["deployments:write", "sandboxes:write", "domains:write"],
)

print(key["key"])  # shown once
```

The plaintext is returned exactly once and MIOSA stores only a hash.
Rotation, scopes, and audit are covered in [API keys](https://miosa.ai/docs/platform/api-keys.md).

## 2. Create a workspace per customer

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

**TypeScript**

```typescript
import { Miosa } from "@miosa/sdk"

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! })

const workspace = await miosa.workspaces.create({
  name: "Northwind Agency",
  slug: "northwind-agency",
  externalWorkspaceId: "acct_123",
})
```

**Python**

```python
import miosa, os

client = miosa.Miosa(api_key=os.environ["MIOSA_API_KEY"])

workspace = client.workspaces.create(
    name="Northwind Agency",
    slug="northwind-agency",
    external_workspace_id="acct_123",
)
```

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](https://miosa.ai/docs/platform/attribution.md).

## 3. Give each user a machine

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

**TypeScript**

```typescript
const sandbox = await miosa.sandboxes.create({
  templateId: "miosa-sandbox",
  workspaceId: workspace.id,
  projectSlug: "booking-portal",
  projectName: "Booking Portal",
  externalUserId: user.id,         // your end user
  externalWorkspaceId: "acct_123", // your customer
})
```

**Python**

```python
sandbox = client.sandboxes.create(
    template_id="miosa-sandbox",
    workspace_id=workspace.id,
    project_slug="booking-portal",
    project_name="Booking Portal",
    external_user_id=user.id,
    external_workspace_id="acct_123",
)

# Everything in one customer's workspace
mine = client.sandboxes.list(workspace_id=sandbox.workspace_id)
```

Each machine has its own filesystem, network, and process tree.
Sizing, templates, and idle defaults are in [Templates and sizing](https://miosa.ai/docs/platform/templates-and-sizing.md).

## Pick what you need

| You want to | Page |
|---|---|
| Provision one sandbox per end user | [Patterns](https://miosa.ai/docs/platform/patterns.md) |
| Run an agent inside your users' machines | [Agents in your product](https://miosa.ai/docs/platform/agents-in-your-product.md) |
| Pick sizes, templates, and idle defaults | [Templates and sizing](https://miosa.ai/docs/platform/templates-and-sizing.md) |
| Put your brand on previews and apps | [Branding and domain setup](https://miosa.ai/docs/platform/white-label.md) |
| Attribute resources and usage to your customers | [Ownership and attribution](https://miosa.ai/docs/platform/attribution.md) |
| Meter usage and charge back | [Usage and billing](https://miosa.ai/docs/platform/usage-and-billing.md) |

## Next

- [Patterns](https://miosa.ai/docs/platform/patterns.md): The three architectures that cover most products, and how to provision each one.
- [Agents in your product](https://miosa.ai/docs/platform/agents-in-your-product.md): Give each user a machine with an agent or harness working inside it.
- [Connect agent accounts](https://miosa.ai/docs/guides/connect-agent-accounts.md): Connect a customer's Claude or ChatGPT plan, or their model key, from your own code.
- [Templates and sizing](https://miosa.ai/docs/platform/templates-and-sizing.md): Sizes, costs, templates, quotas, and idle defaults.
- [Internal Business OS](https://miosa.ai/docs/guides/internal-business-os.md): The internal-company version of this guide.

## Related

- [API keys](https://miosa.ai/docs/platform/api-keys.md): Key families, scopes, rotation, and audit.
- [Ownership and attribution](https://miosa.ai/docs/platform/attribution.md): Workspace and project ownership plus your external IDs.
- [Branding and domain setup](https://miosa.ai/docs/platform/white-label.md): Preview domains, deployment domains, custom domains, and branding.
- [Browser tokens](https://miosa.ai/docs/platform/browser-tokens.md): Short-lived tokens for previews and terminals in the end user's browser.
- [Connect agent accounts](https://miosa.ai/docs/guides/connect-agent-accounts.md): Keys and subscription plans, for your workspace or per end user.
- [Usage and billing](https://miosa.ai/docs/platform/usage-and-billing.md): Per-customer usage and chargeback on a single MIOSA bill.
- [Build gallery](https://miosa.ai/docs/build.md): Step-by-step guides for 20+ product shapes.

## Reference integration

Runnable examples live in [`examples/`](https://github.com/Miosa-osa/miosa/tree/main/examples).
See [`examples/agent-builds-static-app/`](https://github.com/Miosa-osa/miosa/tree/main/examples/agent-builds-static-app) for the "agent builds, previews, and deploys" pattern.
