Core Concepts

MIOSA gives developers and agents a safe development loop without making production mutable. You work in a Sandbox, inspect the result through a Preview, and publish a frozen candidate Release. After MIOSA verifies that candidate, promotion moves the Deployment’s stable URL to the new Version.

If you read only one line, remember this:

Sandbox (mutable) → Preview → Publish → Release (immutable) → Verify → Promote → Deployment (stable URL).

The old Version remains available for rollback. Databases, storage, secrets, and domains remain attached to the Deployment instead of being copied into each release.

The resource hierarchy

MIOSA resolves every operation through a clear ownership chain:

Organization → Workspace → Project → Sandbox or Deployment

• An Organization is the top-level customer or platform account.
• A Workspace isolates a team, customer, or business boundary.
• A Project groups the development and production resources for one product.
• A Sandbox is the mutable place where work happens.
• A Deployment is the durable production identity that owns versions, routes, and bindings.

Every mutation must resolve one unambiguous organization, workspace, project, and target resource. This prevents an agent or CLI command from publishing into the wrong customer or environment.

Development resources

Sandbox

A Sandbox is a mutable, isolated environment where an agent or developer builds an app. It includes a complete development environment with Node, Python, git, package managers, file APIs, and a terminal.

Key properties:

• Mutable and stateful. Files in /workspace persist across commands until the sandbox is destroyed or suspended.
• Executable. Run commands such as npm install, python app.py, or git clone, with structured stdout, stderr, and exit status.
• Agent-friendly file access. Read, write, and synchronize source, configuration, and assets.
• Previewable. Expose a running port through a temporary Preview URL.
• Snapshot-aware. Save, fork, and restore development state without treating that snapshot as a production release.
• Suspendable. Idle compute can pause and later resume from durable state.

A Sandbox is not production. Its files can change at any time, its process can stop, and its Preview can disappear while suspended. Use it to create and test the source that will become a production candidate.

Sandboxes reference →

Preview

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

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

When you create a Preview, you specify the port, usually 3000 or 5173. MIOSA routes that hostname to the Sandbox process. As files change and the development server reloads, the Preview changes too.

Key properties:

• Mutable. Every request reflects the current Sandbox process and files.
• Ephemeral. The URL depends on a running Sandbox and is not a durable customer URL.
• Shareable. Short-lived tokens allow browser access without exposing a workspace API key.

Previews reference →

Production resources

Builder

A Builder is the isolated worker for one publish operation. It freezes the Sandbox source, runs the selected build pipeline, stores the result, and exits. Later edits to the Sandbox cannot change that build.

Three build modes:

The Builder is internal and short-lived. Its job is to make production builds reproducible while the mutable Sandbox remains available for continued work.

Release

A Release is the immutable artifact produced by a successful Builder run. Its content is addressed by a SHA-256 digest and stored outside the Sandbox. The same bytes can be started repeatedly, placed on different hosts, and verified independently.

MIOSA never edits a Release in place. Publishing changed source creates a new Release. That rule prevents a URL from silently serving bytes that do not match its release record.

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 runs a dynamic Release in production. MIOSA’s scheduler places it, the health system checks it, and the reconciler replaces it when the actual runtime no longer matches the desired state.

Key properties:

• Placement. The scheduler selects a compatible host using capacity, region, and policy.
• Scaling. Multiple instances can serve the same Version.
• Recovery. Failed instances can be replaced from the immutable Release.
• Isolation. Production runtimes are isolated from other tenants and from the build Sandbox.

Static deployments do not need Runtime Instances. MIOSA serves their immutable files from the edge.

Runtime Instances reference →

Domain

A Domain is a hostname routed to a Deployment’s active Version. The Deployment owns the route, so a new Version does not require a new customer-facing URL.

• 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 a route does not rebuild an application. Promotion and rollback change which verified Version receives traffic behind the same Deployment URL.

Domains reference →

The immutable publish pipeline

A Deployment is the durable identity of a production app. It owns the stable URL, version history, routes, environment configuration, and data bindings.

A Version connects one Deployment to one immutable Release plus the configuration needed to run it. Publishing creates a candidate Version. It does not make that candidate live merely because the build finished.

Promotion must prove that the candidate is ready, its required configuration is present, its runtime is healthy, and its route serves the expected artifact. Only then does MIOSA update active_version_id.

The production transition is intentionally narrow:

1. Freeze the exact Sandbox source.
2. Build an immutable Release.
3. Create a candidate Version.
4. Verify health, routes, secrets, data bindings, and declared requirements.
5. Promote that exact Version.
6. Prove the public URL serves it.
7. Keep the previous Version available for rollback.

The object relationship remains stable across releases:

Rollback selects an earlier ready Version as active_version_id. The Deployment and its domains do not change identity. For dynamic applications, MIOSA routes traffic to healthy instances of the selected Version and retires instances that no longer belong to the active state.

Deploy overview →

Persistent bindings and data

Sandboxes and Runtime Instances are replaceable. Data Services are durable resources with an independent lifecycle. Replacing a Sandbox, publishing a Release, or rolling back a Version does not delete the Deployment’s database or object storage.

Bindings connect a Sandbox or Deployment to those durable resources. MIOSA resolves the binding and injects the appropriate credentials at runtime.

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 Version does not automatically make an incompatible schema safe. Use backward-compatible expand, migrate, and contract changes so the active and previous Versions can both operate during promotion or rollback.

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 /api/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 /api/v1/sandboxes/{id}/preview-token with the sandbox ID and a TTL (max 24 hours).
2. MIOSA returns an iframe-ready URL with the token embedded.
3. The browser loads that URL, for example https://<slug>.sandbox.miosa.ai?mt=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 /api/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 /api/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