Quickstart

Three tracks. Pick one, finish it, then read the other two.

Track 1: Sandbox to deployment - write a small site inside a sandbox, preview it live, publish to a permanent URL, and verify the URL returned by MIOSA.
Track 2: Agent-driven build - dispatch work into a sandbox from your backend, stream events, collect artifacts, and optionally use a Computer for browser tasks.
Track 3: App Engine - run many workspace apps as Docker containers on one always-on App Engine host while MIOSA owns routing, domains, and proof.

Each track is short enough to run while you are wiring your first integration.

Building a white-label product? If your goal is to ship a SaaS where your customers never see the MIOSA brand, start with the White-Label Integrator Guide instead. It covers per-user provisioning, custom domains, iframe embeds, webhooks, and usage billing from scratch.

Prerequisites

A MIOSA account at miosa.ai with a workspace created.

2. A workspace API key: Dashboard → Settings → API Keys → New key. It starts with `msk_`. Export it:

export MIOSA_API_KEY="msk_u_..."

3. SDK or tooling installed for your language

Track 1: Sandbox to deployment

Step 2 - Write a small static site into `/workspace`.

Step 3 - Start a dev server so you can preview it.

Step 4 - Create a preview and open it.

Open the URL in your browser. You see your index.html served live from inside the sandbox.

Step 5 - Publish to production.

MIOSA freezes a source snapshot, runs a Builder to package the files, stores an immutable Release, and routes the Deployment URL to it. The sandbox remains alive and editable.

Step 6 - Prove the deployment.

The production URL is the URL returned by MIOSA. Do not construct it from the slug. Use deployment proof when you need an operator or CI check that the app is live.

miosa deploy prove <deployment-id> --json

For App Engine deployments, proof checks the deployment row, App Engine host link, host health, durable app target, container route, and public URL probe.

Step 7 - Make a change and republish.

Edit /workspace/index.html again and publish to the existing deployment:

miosa sandbox publish <sandbox-id> 
  --app <deployment-id> 
  --path /workspace 
  --docker-deploy 
  --wait 
  --json

MIOSA creates a new immutable Version and promotes it only after verification succeeds. The previous healthy version remains available for rollback.

Step 8 - (Optional) Attach a custom domain.

See Domains for the DNS setup. Short version: add a CNAME from your domain to the generated host, hit the verify endpoint, MIOSA issues a TLS certificate.

Step 9 - Clean up.

The sandbox is gone. The published deployment and its domain are unaffected - the Release is immutable and lives in object storage independently of the sandbox.

What you just did

Step	What happened
`sandboxes.create`	Created an isolated sandbox from the `miosa-node` template
`files.write`	Wrote a file into `/workspace` inside the running VM
`exec`	Ran a command inside the VM over the exec API
`previews.create`	Opened a tunnel from a public hostname to port 3000 inside the VM
`sandbox publish`	Froze source, ran Builder, stored Release, created Version, and made it live
`deploy prove`	Verified that MIOSA can prove the deployment route and runtime state
`sandbox.destroy`	Terminated the VM; deployment is unaffected

This track treats the sandbox as an agent’s tool environment. You can supply the intelligence from your own backend, or use the Agent Runs API when you want MIOSA to dispatch Claude Code, Codex, or a command runner against a sandbox or computer target.

For the managed runner path, see Agent Runs and Agent Run Groups.

Step 1 - Create a sandbox with external attribution.

If you’re embedding MIOSA in your own product, pass your user/project IDs so you can filter resources later.

Step 2 - Give your agent an exec tool.

The pattern below shows the structure. Substitute callYourLLM with your actual model call.

Step 3 - Let the agent write files directly.

Step 4 - Start the dev server, create a preview, stream it to your user.

The share_url is safe to put in an <iframe> in your end user’s browser. It expires after the configured TTL. Your msk_* key never leaves your server.

Step 5 - Take a screenshot of a Computer (optional).

If your agent needs to verify GUI output or run browser-based tasks, use a Computer instead of (or alongside) a Sandbox.

Step 6 - Publish what the agent built.

Step 7 - Filter all sandboxes for this customer.

Step 8 - Clean up.

What you just did

Step	What happened
External attribution	Tagged every resource with your customer’s IDs - no MIOSA accounts needed for your end users
Exec as agent tool	Ran arbitrary shell commands inside an isolated VM from your agent loop
`files.write`	Agent wrote generated code directly to the sandbox file system
Share token	Minted a browser-safe URL for preview embedding - workspace key stays server-side
Computer screenshot	Optionally gave the agent a real desktop with a vision-accessible screen
`deployments.publish`	Shipped the agent’s output to a permanent immutable URL
`sandboxes.list` with attribution	Queried only resources belonging to one customer - cross-tenant leakage impossible

Track 3: App Engine

Use App Engine when a workspace needs many always-on apps, funnels, APIs, or client sites without provisioning a separate production VM for each deployment. The visible product name is App Engine. The CLI and API still use docker_deploy as the internal compatibility value.

Step 1 - Ensure the workspace App Engine host.

miosa docker-deploy ensure --wait --timeout 600 --json
miosa docker-deploy hosts --json

The host must be active before an App Engine publish can finish.

Step 2 - Publish the sandbox to App Engine.

miosa sandbox publish <sandbox-id> 
  --path /workspace 
  --slug my-app 
  --build-command "npm run build" 
  --run-command "npm run start" 
  --port 3000 
  --docker-deploy 
  --wait 
  --timeout 900 
  --json

The response includes the Deployment and its public_url. That URL may be a MIOSA-managed tenant URL, a workspace deployment domain, a tenant deployment domain, or an exact custom domain. Always show the returned URL.

Step 3 - Prove the app container exists.

miosa docker-deploy doctor <deployment-id> --probe-path / --json

This verifies more than metadata. It checks the App Engine host, durable app target, container route, and a real HTTP probe.

What you just did

Step	What happened
`docker-deploy ensure`	Created or returned the workspace App Engine host
`sandbox publish --docker-deploy`	Published the sandbox artifact as a container on that workspace host
`docker-deploy doctor`	Proved the container and public URL are real

What’s next

Add a real backend. Move from static to dynamic deploys with Publishing and a managed Postgres database.
Authenticate end users. Auth-as-a-service adds a full JWT signup/login flow with one environment variable.
Roll back a bad deploy. Rollback repoints the domain at an older version in seconds.
Understand every primitive. Concepts is the canonical architecture reference.
Build your own product on MIOSA. The Platform / White-label overview covers preview tokens, share URLs, tenant branding, per-user quotas, webhook subscriptions, App Engine domains, and the audit log.
Drop in UI components. @miosa/react, @miosa/vue, and @miosa/svelte provide MiosaPreview, MiosaTerminal, MiosaFileTree, and MiosaUsage. See UI Components.
See a full white-label example. The reference integration shows a complete platform embedding.
Extend Claude Code with MIOSA skills. 5 pre-built skills at github.com/Miosa-osa/miosa-skills give Claude Code sandbox, computer, and deploy primitives. See Skills.
API wire format. API Reference documents every endpoint.