FAQ

The Quickstart recommends Track 1: sandbox to deployment first. Your first success is a site live at the production URL MIOSA returns, verified end to end. The full walkthrough is Build and deploy a Next.js app.

With a MIOSA API key in an Authorization: Bearer header, or with a JWT from POST /auth/login. See Authentication and API keys.

Install the miosa CLI (v2.2) from npm, Homebrew, the install script, or a release archive. Then run miosa login for the device-code flow and miosa whoami to confirm the active organization and workspace. See Install the CLI.

Create one under Workspace → Settings → API Keys. The plaintext is shown once and only the hash is stored. Key families are msk_u_ (user), msk_p_ (tenant platform), and msk_a_ (operator admin, not self-service). Default rates are 600 requests per minute for a user key and 30,000 for a platform key; rotate every 90 days. See API keys.

Not yet. Dedicated test-mode keys are not live: msk_u_* and msk_p_* keys hit the billable production substrate. See Availability and roadmap for the schedule.

Free-form metadata, plus the queryable external_user_id, external_workspace_id, and external_project_id. See Metadata and labels.

us-west (default), us-east, and us-mia, all generally available. A resource lives in one region for its lifetime, so create one per region. EU and APAC are on the roadmap. See Regions.

Use a Sandbox for code, files, and processes. Use a Computer when you need a visible desktop, a browser login, or human takeover. Use App Engine when you need a durable, always-on URL.

A headless microVM that is persistent by default, with /workspace as the editable root, booted from a template (usually miosa-sandbox). The default size small is 2 vCPU, 4096 MiB RAM, and 10240 MiB disk, and responses carry a versioned resource_contract. See Sandboxes and Sizing and limits.

A Computer is a durable cloud Linux desktop (Xfce and Firefox) with screenshot, click, type, and streaming, plus human takeover. You embed or share it through computer.urls()["desktop_url"]. See Computers and Embed a live desktop.

timeout_sec is 1 to 86400 seconds, default 3600. always_on disables timeout enforcement subject to tenant policy. Set idle_timeout_sec to pause a persistent sandbox after a period of inactivity; it is off unless you set it. See Timeouts and auto-stop.

provisioning, running, paused, error, and destroyed. See Sandbox lifecycle.

No. Pause keeps the sandbox id and the filesystem; resume brings it back. Destroy is what removes saved state. See Snapshots and persistence.

Restore builds a new sandbox from a checkpoint; fork branches a running sandbox into an independent one. Both leave the source unchanged. See Snapshots and persistence.

No. A snapshot captures the sandbox VM state only. External databases, object storage, connectors, and third-party services are not rolled back with it. Keep durable state in a data service. See Data overview.

claude-code, codex, osa, and custom, set with miosa agent new --harness. Agent Run providers also include claude, pi, and hermes. See Agents CLI and Configure an agent.

miosa agent new reviewer --harness claude-code --instructions-file review.md
miosa agent run reviewer "review PR 42" --sandbox my-box
miosa run list                 # follow, stop

See Agents CLI.

OSA is MIOSA’s open-source agent. It installs on your machine, runs as an MCP client, and runs headless with osa run "..." when you do not want the terminal UI. See MCP and the CLI reference.

No. Agents use your own model connections, never MIOSA platform keys. Create an agent-scoped key and add a model connection before the first run. See Agents CLI.

Agents work against a device: a Sandbox Worker, a Computer, or a local/BYOC device. App Engine is a hosting target, not an agent device. See Agent devices and Choose an agent device.

Yes. Call the primitives from your own backend, or start with the Agent Development Kit (ADK). See Integrating an AI agent.

Screenshot, decide, take one action, screenshot again. Coordinates are screen pixels with the origin at the top left. See Computer use quickstart.

Yes. Take over a Computer desktop directly, or embed the live desktop in your own UI. See Embed a live desktop.

Computer use bills as Computer compute while the machine is running. See Pricing and limits.

Running compute (vCPU-seconds plus GiB-seconds), paused storage, runtime instances, storage and egress, and managed Postgres or Redis. The full list is on Pricing and limits.

Storage only. Billing for compute stops when the sandbox leaves running. See Sizing and limits.

xs (1 vCPU, 2 GiB, 10 GiB) through xl (16 vCPU, 32 GiB, 80 GiB), with small as the default. See Sizing and limits.

Concurrent sandboxes per plan (Developer 10, Business 250, Enterprise 500; upgrade or raise it through support), timeout_sec 1 to 86400, a 300 second maximum exec timeout, a 100 MB maximum upload, and a 5 minute browser token TTL. See Pricing and limits.

600 requests per minute per workspace and 60 per minute per endpoint group, with 429 and Retry-After on overrun. See Rate limits.

The Quotas API sets max_sandboxes, max_concurrent, max_storage_gb, and max_credit_cents per external_user_id, enforced at create time.

MIOSA bills you once; you charge your customers using attribution. The Usage Rollup API groups by external_user_id, external_project_id, or workspace_id. See Usage and billing.

It depends on the grant. Purchased credits (top-ups and auto-recharge) do not expire. Recurring plan credits expire at the start of the UTC day after the 30-day billing period. Promotional credits (the one-time welcome grant and promo-code redemptions) expire 180 days after they are granted. The nearest expiry is reported as credit_expiry_at on GET /api/v1/credits/balance. See Pricing and limits.

SOC 2 Type I is complete, and the report is available to customers and prospects under NDA. SOC 2 Type II is in progress, with the observation window underway. See Trust.

MIOSA runs HIPAA-compliant infrastructure for healthcare workloads, and business associate agreements (BAAs) are available for Enterprise customers. See Trust.

In United States data centers we provision, network, and manage directly; MIOSA is not a reseller of a hyperscaler. The three live regions are all in the US, and a resource cannot move between them after creation. See Regions and Trust.

Values are encrypted with ChaCha20-Poly1305. Sandboxes see an opaque miosa-tok-<hex> placeholder that is swapped at egress, so no one - including MIOSA engineers - can re-read a stored value. See Secrets.

Egress audit events are retained 90 days. Usage and credit records are kept separately. There is no published zero-retention mode. See Data retention.

No. There are no pk_* publishable keys: API keys are server-only. Browser and embed access uses short-lived scoped tokens instead (mp_ preview, ms_ share, and browser tokens). See API keys and Browser tokens.

Your platform maps to one MIOSA organization, with a workspace per downstream customer and a project per thing they build. End users never need a MIOSA account. See White-label platform architecture.

A preview domain (https://{port}-{slug}.sandbox.{preview_domain}), a deployment domain (https://{slug}.{deployment_domain}), and a MIOSA fallback (https://{slug}.{organization_slug}.miosa.app). See Branding and domain setup.

Never put an msk_* key in a browser. Your backend mints short-lived scoped tokens, and end-user-scoped secrets and OAuth are keyed on external_user_id. See Attribution and White-label credentials.

MIOSA charges the organization owner for all usage in one bill. Charge back to customers by grouping the Usage Rollup on workspace_id or the external_* fields. See Usage and billing.

Yes. Set custom_app_name, custom_logo_url, support_url, desktop_wallpaper_url, and powered_by_visible through PUT /api/v1/tenant/branding. See Branding and domain setup.

Yes. The reference map includes MIOSA BusinessOS, a self-hosted business workspace you run internally rather than launch as a product. See Agent company reference map.

Managed connectors attach in-VM tools without shipping you vendor tokens; the sandbox gets a placeholder swapped only for that provider’s endpoint. See Managed connectors.

Pure reasoning needs no device; files and code use a Sandbox; browser and desktop work use a Computer; private customer resources use a local device; serving traffic uses App Engine. See Choose an agent device.

Follow the build-your-own-platform checklist: workspace, credentials, runtime profile, primary device, dispatch, stream, export, snapshot, publish, scale. See Build an agent-company platform.

SOMA (Secure Optimized Machine Architecture) is MIOSA’s own open-source Rust VMM on Linux KVM, giving each sandbox one hardware-isolated VM with its own kernel. See SOMA.

No. Firecracker is MIOSA’s default sandbox engine; SOMA is early access and enabled per organization. See SOMA.

Email support@miosa.ai with the subject SOMA early access: followed by your organization name. See SOMA.

Sandboxes, previews, publishing, data, and white-label are generally available. Computers, dynamic deployments, App Engine, and tenant deployment domains are in partner preview; GPU-backed sandboxes are not productized and remain on the roadmap. See Availability and roadmap.

Open an in-product ticket from the dashboard - the fastest path for anything involving a resource - or email support@miosa.ai for non-resource questions. See Support.

The resource id, the operation you ran, a timestamp with timezone, the x-request-id, and the exact error message. See Support.

The status page for live health, the changelog for shipped changes, and Known limitations for current gaps. See Support.

Join the MIOSA Discord for questions and announcements.