Core Concepts

MIOSA is a cloud platform for building, previewing, and deploying applications - primarily by AI agents, but equally usable by developers directly. Every operation maps to one of the six primitive resource types below. Everything else is composition.

If you read only one sentence: Sandbox → Preview while editing → Publish → Version → Deployment → Domain. That is the product pipeline.

Infrastructure model

MIOSA exposes product primitives, not raw infrastructure. You create sandboxes, previews, deployments, computers, domains, and data services. MIOSA handles placement, isolation, routing, health checks, certificates, and cleanup behind those objects.

The six concrete things

Sandbox

A Sandbox is a mutable isolated environment where an agent or developer builds an app. It ships with a full development environment: Node, Python, git, package managers, and a terminal.

Key properties:

• Mutable and stateful. Files in /workspace persist across exec calls until the sandbox is destroyed or auto-suspended.
• Exec surface. Call exec to run any shell command - npm install, python app.py, git clone - and get stdout/stderr back.
• File I/O. Read and write files at arbitrary paths. Agents use this to generate code, configs, and assets.
• Preview tunnels. Open any port inside the sandbox to the public internet via a Preview URL (see below).
• Snapshots. Freeze the full VM state, fork from it, or restore it. Enables fast branching and rollback during development.
• Auto-suspend. Idle sandboxes suspend after a configurable timeout to save compute. Resume is near-instant from snapshot.

A Sandbox is not production. Production traffic never routes to a sandbox. The sandbox is where you build the thing that will become production.

Sandboxes reference →

Preview

A Preview is a temporary public URL that tunnels to a port inside a running sandbox.

https://5173-abc12345.sandbox.miosa.app

When you create a preview, you specify the sandbox port (typically 3000 for a dev server). MIOSA’s edge proxy maps that hostname to the sandbox’s internal IP and port. As files change inside the sandbox and the dev server hot-reloads, the preview updates live.

Key properties:

• Mutable. The preview reflects the live state of the sandbox at every request.
• Ephemeral. The preview URL dies when the sandbox is destroyed or suspended.
• Share tokens. For embedding previews in your own product’s UI, your backend mints a short-lived share token. The token is safe to put in a browser <iframe> - it grants time-limited preview access without exposing the workspace API key.

Previews reference →

Builder

A Builder is the internal publish worker that runs for one publish job. It freezes the sandbox source at publish time, runs the build pipeline, stores the result, and exits.

Three build modes:

The Builder is internal. You never address it directly. It exists so production builds are reproducible (source is frozen at publish time, not the live mutable sandbox) and so your sandbox keeps running while the build executes.

Release

A Release is the immutable artifact produced by a Builder run. It is sha256-keyed and stored in object storage. The same release can be deployed to any number of regions, booted N times, and referenced by multiple versions - the content never changes.

Two shapes:

• Static release - a tarball of files (index.html, app.js, assets). MIOSA’s edge serves them directly. No Runtime Instances required.
• Dynamic release - a server app artifact. Served by production runtimes.

Releases reference →

Runtime Instance

A Runtime Instance is a production runtime for a dynamic deployment. It serves real traffic and is managed by MIOSA’s scheduler and reconciler.

Key properties:

• Scheduler placement. Instances are placed on fleet hosts by a scheduler that watches CPU, RAM, and region capacity.
• Horizontal scaling. Multiple instances can serve a single version simultaneously.
• Health checks. The reconciler replaces instances that fail health checks without manual intervention.
• Isolation. Each instance is isolated from other tenants and from the original build sandbox.

Static deployments have no Runtime Instances - files are served from the edge directly.

Runtime Instances reference →

Domain

A Domain is a DNS hostname routed to a deployment’s active version. Three tiers:

• my-app.my-workspace.miosa.app - MIOSA-managed fallback URL, instant, no DNS change needed.
• my-app.apps.yourplatform.com - tenant deployment domain for generated apps.
• app.yourcustomer.com - custom domain your customer brings; MIOSA auto-provisions a TLS certificate via Let’s Encrypt.

Changing the domain mapping does not rebuild the app - it updates routing only. This is how rollback works: repoint the domain at an older ready version.

Domains reference →

Deployments, Versions, and the publish pipeline

A Deployment is the stable product object - the thing the world thinks of as “the live app.” It holds an active_version_id. Publishing creates a new Version, which references a Release. Promoting a version updates active_version_id; rollback resets it.

Full object hierarchy:

Rollback is Version 16 → active_version_id. Runtime Instances for Version 17 drain and exit; Version 16 instances start. Domain routing never changes - the domain still points at the same Deployment.

Deploy overview →

Data services

Sandboxes and Runtime Instances are ephemeral. Data Services are not. MIOSA provisions and operates them outside the version lifecycle - destroying a sandbox or publishing a new version does not affect them.

Both the sandbox and runtime instances receive credentials as environment variables at boot:

DATABASE_URL=postgresql://user:pass@host/dbname
REDIS_URL=redis://host:6379
STORAGE_BUCKET=miosa-ws123-uploads
AUTH_URL=https://auth.miosa.app/proj_abc
AUTH_JWT_SECRET=...

Destroying a sandbox does not destroy its database. Publishing a new version does not run migrations - MIOSA gives you the connection string; you run db:migrate in your deploy hook.

Data overview →

Computers (desktop product)

Computers are full desktop environments running in the cloud with screenshot, click, type, and keyboard APIs. They are a separate product surface from Sandboxes - different lifecycle, different use cases.

Use Sandboxes for building apps. Use Computers when your agent or workflow needs a real screen.

You can also bring your own hardware (Mac, Linux, Windows) and register it as a Computer host via BYOC.

Computers overview →

White-label tenancy

MIOSA is designed for platforms - you build a product on top of MIOSA, and your customers never know MIOSA exists.

The tenancy model:

• One MIOSA organization per customer platform. A platform account has one organization slug and server-side msk_* keys.
• Workspaces and projects for downstream customers. Use MIOSA workspaces for clients and projects for the apps, sites, documents, and workflows they create.
• External attribution for your IDs. Pass external_workspace_id, external_user_id, and external_project_id when you need your database IDs on usage, audit, and list filters.
• Server-side key, never in the browser. For browser-side access (embedding a preview, opening a terminal), your backend mints a short-lived scoped token. The msk_* key stays server-side.

Filters are always organization-scoped server-side. You cannot cross organizations by passing different workspace, project, or external IDs.

Platform / White-label overview →

External attribution

External attribution is how you map MIOSA resources to your own users, projects, and tenants without creating MIOSA accounts for them.

Three opaque string fields are accepted on every resource that supports creation:

These fields are stored and returned on reads. They are filterable on list endpoints. Usage rollup (GET /v1/usage?group_by=external_user_id) aggregates compute and storage consumption per attributed user - enabling per-customer chargeback without any secondary accounting pipeline.

MIOSA never interprets or validates the content of external attribution fields. They are always stored as-is.

Attribution reference →

Preview tokens

A preview token (prefix mp_*) is a short-lived signed token that authorizes a browser to load a sandbox preview without receiving the workspace API key.

The typical flow:

1. Your backend calls POST /v1/preview-tokens with the sandbox ID and a TTL (max 24 hours).
2. Your backend passes the token value to the browser - for example, as a page prop or a short-lived cookie.
3. The browser constructs the preview URL: https://<slug>.sandbox.miosa.app?token=mp_...
4. MIOSA’s edge verifies the token server-side and proxies the request to the sandbox port. The token value never grants broader access.

Preview tokens are non-renewable and non-transferable. When the TTL expires the URL returns 401. Your backend mints a new token to restore access.

Browser Tokens reference →

Share tokens

A share token (prefix ms_*) is a revocable public share URL for a sandbox preview - analogous to a “share link” in a document editor.

Key differences from preview tokens:

Share tokens are useful for demos, client reviews, or collaborative previews where the recipient does not have a user account in your system. The link can be embedded as a plain URL - no Authorization header needed.

Previews reference →

Tenant preview domain

A tenant preview domain is a custom hostname that replaces MIOSA fallback preview domains in every sandbox preview URL your end users see.

When you register and verify a preview domain (for example, preview.yourproduct.com), sandbox previews for your workspace are served at:

https://<sandbox-slug>.preview.yourproduct.com

Setup is a two-step DNS verification: add a CNAME record pointing to MIOSA’s edge, then call POST /v1/tenant/preview-domain/verify. MIOSA auto-provisions a wildcard TLS certificate via Let’s Encrypt once the CNAME resolves.

One preview domain per workspace. The domain applies to all sandboxes in the workspace.

Custom Domains reference →

Tenant branding

Tenant branding controls what your end users see on MIOSA-rendered pages - specifically 4xx and 5xx error pages displayed when a sandbox is unavailable, a preview URL is invalid, or a custom domain is not yet verified.

Configurable fields:

Branding is set via PUT /v1/tenant/branding and takes effect within 60 seconds across all edge nodes.

MIOSA’s own wordmark never appears on branded error pages.

Tenant branding API →

Three naming layers

One thing trips up every new reader: “Computer” has a specific meaning in MIOSA.

Sandboxes are not Computers. Runtime Instances are not Computers. Computers are Computers. When you encounter older docs or code that uses “Computer” generically, substitute “Sandbox” or “Runtime Instance” based on context.

What’s next