Sandbox to deployment

Start with Track 1: Sandbox to deployment. The recommended first walkthrough. Your first success is a small site running at the production URL returned by MIOSA, with its deployment verified. Complete that path before adding agent orchestration or another runtime.

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

Account and workspace

Create a MIOSA account at miosa.ai and a workspace.

API key

Create a key in Settings → API Keys for the intended workspace. See API keys for key types and scopes. Export your key in the terminal where you will run the examples:

export MIOSA_API_KEY="msk_u_..."

Install tooling for your language

Step 1 - Create a sandbox.

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 get <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 deploy create --from-sandbox <sandbox-id> 
  --name <deployment> 
  --dir /workspace 
  --type 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	What happened
`sandboxes.create`	Created an isolated sandbox from the `miosa-sandbox` 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

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.